API Errors and Retries

Every response uses the same envelope for success and failure:

{"code": 0, "data": {}, "msg": "success"}

On failure, code is non-zero and data may be null or carry structured detail (the size limit that was exceeded, the remaining login attempts, and so on). msg is localized to the request language — never branch on msg text, always branch on code.

HTTP Status Mapping

HTTP status and business code are not 1:1. The same code can appear with different HTTP statuses (2003 is 403 when a JWT cannot be decoded but 400 for a wrong password), so use the HTTP status for coarse classification and the body code for precise branching.

Business Code Reference

The tables below cover every error code defined by the current version. Unused numbers inside a range are reserved — do not implement branches for them.

The HTTP column lists the status the backend actually raises today. 400 means no explicit status was set, which is the BusinessError default. A few codes use different statuses on different endpoints (1004, 3001, the 6000 family, 6100); the table shows the most common value and the response is authoritative.

General errors (1000-1999)

For 1001, data.errors is a dictionary of field name to message array, not an array:

{
  "code": 1001,
  "data": {
    "errors": {
      "email": ["Invalid email address"],
      "password": ["String should have at least 8 characters"]
    }
  },
  "msg": "Validation error"
}

Authentication errors (2000-2999)

2001 also covers the superseded token in single-session mode (msg_key is session_expired_new_login) and blacklisted tokens.

Permission errors (3000-3999)

3000 is also what an API key receives when its resource binding does not match (msg_key is api_key_no_agent_access / api_key_no_workflow_access); see the API Keys API.

Resource errors (4000-4999)

Registration and accounts (5000-5099)

This range always returns HTTP 400. 5007 may carry data and 5008 carries data.remaining_seconds for a precise message.

Duplicate conflicts (5100-5199)

This range always returns HTTP 400. Retrying cannot succeed — rename the resource or switch to the update endpoint.

Forbidden operations (5200-5299)

This range always returns HTTP 400. To change ownership, use the transfer-ownership endpoint described in the Teams API.

Login security (5300-5399)

Rate limiting (5400-5499)

5400 carries the dimension that was exceeded, for example {"limit": 100, "period": "hour"} for bulk email or {"requested": 3, "remaining": 1}.

Knowledge base (6000-6099)

6007 mirrors 6201 for Agents: the resource exists but the current user or API key is outside its access scope. Surface a permission request instead of retrying.

Models (6100-6199)

6103 is the only code that reliably returns HTTP 429. 6104 and 6106 both mean “unavailable right now”, but 6104 requires adding a team model authorization while 6106 only requires re-enabling is_enabled on an existing one.

Agents and conversations (6200-6299)

SSO (6300-6399)

This range always returns HTTP 400. 6306 appears on the login endpoint, so it tells the caller to switch to SSO rather than retry.

Handling Table

Retryable and Non-Retryable

Network timeouts, 503/504, temporarily unavailable providers, 5400 and 6103 throttling, and some background task failures can be retried with exponential backoff.

Do not blindly retry:

• 1001-1004 — the request itself is invalid; a retry returns the same result.
• 3000-3004, 6007, 6201 — permission problems; fix the authorization first.
• 2001, 2002, 2004 — credential or account state problems.
• 4000-4005 — the resource does not exist; verify the ID and context.
• 5100-5214 — constraint conflicts; the request must change.
• 6104, 6106 — model authorization or enabled state.
• 6306 — this deployment has disabled password login.

SSE Error Handling

Streaming endpoints cannot change the HTTP status once the response headers are sent, so mid-stream failures arrive as error events inside the stream:

• After an Agent stream error event, keep the text received so far and the message_id, then decide whether to retry or surface it. The message may already be persisted, so check conversation messages before retrying to avoid duplicate questions.
• After a workflow stream disconnects, resume with stream_url and the last received event sequence number instead of calling POST /workflows/{workflow_id}/run again.

The full event list for both streams is in Streaming Events.

Related Documentation

• Authentication & Login API — where 2000-2004, 5300-5316, and 6306 come from
• API Keys API — 2001, 2002, 3000, and API key binding limits
• Teams API — 3002-3004, 4004, 4005, 5102, 5103, and 5206-5210
• Users API — 5002, 5003, 5212-5214, and password lifecycle errors