Rate limits and error codes
OctaDezx API rate limits: 60 requests a minute per API key, 30 AI turns a minute on the Agent API, messenger limits per IP and business, plus every error code and how to handle it.
Status: available. The OctaDezx API allows 60 requests a minute per API key on every key-authenticated endpoint, and Agent API turns share an extra bucket of 30 AI turns a minute per key. Messenger client endpoints allow 60 requests a minute per IP and 1200 per business. A 429 carries Retry-After in seconds, except usage_limit_reached, which lasts until the plan period resets. Every error body is { error, code } plus context, and errors after a customer message was stored include messageAccepted so you can read the conversation before resending.
Limits
| Scope | Limit | Code when exceeded |
|---|---|---|
| Each API key, every key-authenticated endpoint | 60 requests per minute | rate_limited, Retry-After: 60 |
| AI turns per API key (Agent API) | 30 per minute | rate_limited, Retry-After: 60 |
| Business message allowance (plan) | Per billing period, shared with every channel | usage_limit_reached, no Retry-After |
| Messenger client endpoints, per IP | 60 requests per minute | rate_limited, Retry-After: 60 |
| Messenger client endpoints, per business | 1200 requests per minute | rate_limited, Retry-After: 60 |
Error codes
Back off for the Retry-After seconds. Do not retry a turn rejected for usage_limit_reached until the plan period resets or the plan is upgraded.
| Code | HTTP | Meaning |
|---|---|---|
| invalid_request | 400 | A field is missing or malformed. |
| unauthorized | 401 | Missing, invalid or revoked API key, or an unverified user on a client device route. |
| not_found | 404 | No such route, or the conversation belongs to another business. |
| conversation_user_mismatch | 409 | The conversation is bound to a different user. Start a new one. |
| rate_limited | 429 | See the limits above. |
| usage_limit_reached | 429 | The business's plan allowance is used. |
| server_error | 500 | Unexpected. |
| ai_unavailable | 503 | The AI turn failed. The customer message was recorded. |
| transcript_unavailable | 503 | The customer message write could not be confirmed. |
| service_unavailable | 503 | A dependency is unavailable. |
Error body
{ "error": "Conversation not found for this business", "code": "not_found" }Frequently asked questions
- What is the OctaDezx API rate limit? 60 requests a minute per API key, with Agent API turns also limited to 30 a minute per key. Messenger client endpoints allow 60 a minute per IP and 1200 per business.
- What should I do on a 429? Wait for the Retry-After seconds. A usage_limit_reached 429 lasts until the plan period resets.
- What does messageAccepted mean on an error? That the customer message was stored, or that its write is uncertain. Read the conversation before resending, because the agent may already have acted.