Error Codes & Troubleshooting
API errors include structured codes and actionable messages. Use this guide to diagnose issues and keep integrations running smoothly.
Error Response Format
{
"error": {
"code": "invalid_request",
"message": "publishAt must be a future timestamp",
"details": {
"field": "publishAt",
"reason": "value is in the past"
}
}
}
| Field | Description |
|---|---|
code | Machine-friendly string describing the error category. |
message | Human-readable summary you can display to users. |
details | Optional object with field-level context. |
Common Error Codes
| Code | Meaning | How to Resolve |
|---|---|---|
unauthorized | Missing or invalid credentials. | Check API key, OAuth token, and X-Altyaa-Workspace header. Regenerate tokens if needed. |
forbidden | Authenticated but lacks permission. | Ensure the key or user has the required scope/permission (e.g., posts.write). |
invalid_request | Payload validation error. | Review details for field-specific issues. Validate data types and constraints before sending. |
not_found | Resource does not exist or is outside workspace scope. | Confirm IDs belong to the workspace and were not deleted. |
conflict | Action contradicts current state (e.g., duplicate slug). | Adjust request or fetch latest state before retrying. |
rate_limit_exceeded | Too many requests in a window. | Follow guidance in Rate Limits & Quotas. |
service_unavailable | Temporary downtime or external dependency failure. | Retry with exponential backoff. If issue persists, check status page. |
Troubleshooting Checklist
- Validate Authentication: Confirm the token has not expired. For OAuth, refresh tokens before they lapse (see Authentication & OAuth).
- Check Payloads: Compare request payloads against the API reference. Use JSON schema validation during development.
- Inspect Logs: Enable verbose logging in your integration and capture
requestIdfrom response headers for support. - Use Sandbox: Replicate the issue in the sandbox environment to isolate production data concerns.
- Monitor Webhooks: Ensure webhook endpoints return
2xxquickly; unhandled retries can create duplicate processing.
Support Escalation
- Gather
requestId, timestamp, endpoint, and payload snippet (omit sensitive data). - Check the Status Page for platform-wide incidents.
- Contact support via the Developer Portal with context and recent logs.
For deeper insight into data flow and scheduling behavior, continue to Scheduling & Data Model.