API calls fail: a checklist

Read the code in the error envelope (or the error event) first: it names the problem. The full list is in Errors. This checklist covers the common ones, in the order they're checked.

Check these in order

1. 1

   401: the key

   MISSING_API_KEY or INVALID_API_KEY. Send your sk-so- key in X-Api-Key (not Authorization). Watch for trailing newlines from environment files. A pk-so- key only works on the widget.

2. 2

   400: the agent and message

   MISSING_AGENT_ID or MISSING_MESSAGE. Send X-Agent-Id (or agent_id) and a non-empty message.

3. 3

   404: the agent

   AGENT_NOT_FOUND: the id is wrong, or the agent is on another account. Copy it from the agent's Deploy tab.

4. 4

   403: the agent is paused

   AGENT_INACTIVE. Set it to Active on its Settings tab.

5. 5

   402: credits

   OUT_OF_CREDITS. Buy credits or turn on auto top-up.

6. 6

   429: the rate limit

   RATE_LIMIT_EXCEEDED. The agent's limit (60 a minute for new agents) is shared by every channel. Wait the seconds in X-RateLimit-Reset.

7. 7

   422: the body

   VALIDATION_ERROR: for example a message over 32,000 characters. Read details.

8. 8

   200 but an error event

   The stream started, then failed. LLM_AUTH_ERROR: fix the agent's provider key. LLM_RATE_LIMITED or LLM_UNAVAILABLE: your provider; retry later. TIMEOUT: the reply passed 120 seconds. INTERNAL_ERROR: check the agent has a provider key, then email support with the request_id.

9. 9

   Nothing arrives until the end

   Something is buffering. Use curl -N; turn off response buffering on proxies between you and the API; read the body as a stream, not with res.json() or res.text().