DoubleX AgentesDocs

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:

JSON
{ "error": "Agent not found" }

Some errors also have a stable code. Use the code (not the text) to decide what to do:

codeStatusMeaning
no_credits402The organization is out of credits. An admin needs to add more in Settings › Usage and credits.
plan_required402The organization has no plan yet: only the first diagnostic is free. The owner chooses a plan in Settings › Plan and billing.
agent_budget402The 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_provider400 or 409No AI model is available to you.
model_unavailable400The requested model isn't in the catalog or isn't enabled for you.
provider_error502The model provider failed. Try again.

Status codes#

StatusWhen it happens
200 / 201Success. 201 when something was created.
202Accepted and running in the background (webhooks and triggers/{id}/run).
400Invalid body: a missing field, a size outside the limit, malformed JSON. The message says which field.
401No key, or an invalid or revoked key.
402Out of credits (no_credits), no plan (plan_required) or the agent used up its monthly budget (agent_budget).
403You can see the item but can't change it, or the action works only in the browser.
404The 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.
409State conflict: the conversation is already running, the trigger is turned off, or the connector needs to be reconnected.
413File too large (the Brain accepts up to 20 MB per file).
422The 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.
5xxServer 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:

NDJSON
{"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/credits or doublex credits.
  • With no balance, direct chat and text-to-schedule conversion respond 402 no_credits. Agent conversations respond with the error event 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#

WhatLimit
Message to an agent100,000 characters
Agent response time800 seconds per message
Concurrent conversationsOne answer per conversation. To run in parallel, use different conversations.
Brain file20 MB per file; text beyond 2 million characters is split into parts
File downloaded from Creations2 MB
Connector tool result20,000 characters
Scheduled triggerAt most once every 5 minutes
Webhook body200,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.