Guides › Integration
Errors and limits
Status codes, error format, credits, message language and API limits.
Error format#
When something goes wrong, the API responds with an HTTP error status and JSON with the message in error:
{ "error": "Agent not found" }Some errors also have a stable code. Use the code (not the text) to decide what to do:
code | Status | Meaning |
|---|---|---|
no_credits | 402 | The organization is out of credits. An admin needs to add more in Settings › Usage and credits. |
plan_required | 402 | The organization has no plan yet: only the first diagnostic is free. The owner chooses a plan in Settings › Plan and billing. |
agent_budget | 402 | The agent reached this month's budget. Its owner can raise the limit in the agent's settings; otherwise it comes back when the month turns over. |
no_provider | 400 or 409 | No AI model is available to you. |
model_unavailable | 400 | The requested model isn't in the catalog or isn't enabled for you. |
provider_error | 502 | The model provider failed. Try again. |
Status codes#
| Status | When it happens |
|---|---|
200 / 201 | Success. 201 when something was created. |
202 | Accepted and running in the background (webhooks and triggers/{id}/run). |
400 | Invalid body: a missing field, a size outside the limit, malformed JSON. The message says which field. |
401 | No key, or an invalid or revoked key. |
402 | Out of credits (no_credits), no plan (plan_required) or the agent used up its monthly budget (agent_budget). |
403 | You can see the item but can't change it, or the action works only in the browser. |
404 | The item doesn't exist or you don't have access to it. The API doesn't tell the two cases apart, so it doesn't reveal what exists. |
409 | State conflict: the conversation is already running, the trigger is turned off, or the connector needs to be reconnected. |
413 | File too large (the Brain accepts up to 20 MB per file). |
422 | The file or text arrived but couldn't be used: unsupported format, a PDF with no text, a phrase that doesn't turn into a schedule. |
5xx | Server or AI provider failure. Retry with increasing backoff. |
Errors during streaming#
Routes that stream their response (agent conversations and direct model chat) have already started responding with 200 when the problem shows up. In these cases the error arrives as an event in the middle of the stream:
{"type":"error","message":"Your organization is out of credits."}
{"type":"done","status":"failed"}Always handle the error event and done with status: "failed". Details are in Conversations and Chat.
Credits#
When the organization uses the platform's models, each answer consumes credits based on the model's cost. Usage through the API and the CLI comes out of the same balance as the app.
- Before heavy usage, check the balance with
GET /api/creditsordoublex credits. - With no balance, direct chat and text-to-schedule conversion respond
402 no_credits. Agent conversations respond with theerrorevent in the stream. - A conversation that's cancelled or fails midway is still charged for what was already processed.
Message language#
Error messages come in the language of the key's owner (one of the app's 14, such as Português, English, Español, Français or 日本語), the same one chosen in the app. To change it through the API, use PATCH /api/me with {"language": "en"}. If the person hasn't picked a language yet, the request's Accept-Language header is used and, without it, the organization's default language.
Format validation messages (for example, name: Too small) may be in English.
Limits#
| What | Limit |
|---|---|
| Message to an agent | 100,000 characters |
| Agent response time | 800 seconds per message |
| Concurrent conversations | One answer per conversation. To run in parallel, use different conversations. |
| Brain file | 20 MB per file; text beyond 2 million characters is split into parts |
| File downloaded from Creations | 2 MB |
| Connector tool result | 20,000 characters |
| Scheduled trigger | At most once every 5 minutes |
| Webhook body | 200,000 characters |
There's no requests-per-minute limit, but use common sense: prefer a few larger calls over many small ones, and don't run sweeps in a loop.
Lists and pagination#
Lists (GET /api/agents, GET /api/tasks, GET /api/skills etc.) return everything you can see, with no pagination. Filter in your code or use each route's filters.