Errors and troubleshooting
Every Agent API error code, what it means and what to do.
- Can I rely on the error message text in my code?No. Branch on error.code, which is stable. message is human-readable and can change.FAQ
- How do I fix 402 out_of_credits?Your credit balance is used up. Add credits in Console › Billing › Credits. Retrying without topping up won't help.Troubleshooting
- How do I know if the Agent API is having problems?Check status.clatterlabs.com for live health and incidents. Persistent 502 or 503 errors are a sign to look there.FAQ
- How should my code handle Agent API errors?A simple strategy: fix 4xx request errors, wait on 429, stop on 402, and retry 502/503 with backoff.How-to
- I get a CORS or network error calling the API from my web page. Why?Browsers block some requests, and keys don't belong in front-end code anyway. Call the Agent API from your backend instead.Troubleshooting
- My create request fails though input is set. What else can be wrong?Check Content-Type: application/json, valid JSON (escape quotes and newlines), and that you're sending POST to /v1/runs.Troubleshooting
- My requests fail with a strange HTML page or a 403 that isn't JSON. Why?A non-JSON response usually comes from a proxy, firewall or security filter in between. Try another network or a standard HTTP client.Troubleshooting
- My run ended with error code run_failed. What can I do?run_failed means the run started but couldn't finish for a reason other than credits. Read the message and steps, then retry with clearer instructions.Troubleshooting
- My run has been "running" for a long time. Is it stuck?Long tasks can take many steps. Check the event stream for recent steps; if nothing moves for a long time, cancel and retry.Troubleshooting
- What do all the Agent API error codes mean?Every Agent API error code with its HTTP status, meaning and what to do, in one table.Reference
- What does 400 bad_request mean when creating a run?input is missing or empty, or tier isn't auto, flash, max or heavy. The message says which.Troubleshooting
- What does 403 early_access mean?The account isn't in the early-access program yet. Check you're using the right Account ID, then contact support with your Account ID.Troubleshooting
- What does 403 no_cloud_account mean?Your account hasn't been set up for Cosmos Agent yet. Follow the docs' steps, and contact support with your Account ID if it persists.Troubleshooting
- What does 404 not_found mean on the Agent API?No run with that id exists on your account. Check the id and the Account ID, or the URL path.Troubleshooting
- What does 405 method_not_allowed mean?You used the wrong HTTP method for this endpoint, such as GET on /v1/runs/{id}/cancel. Use the method in the reference.Troubleshooting
- What should I do about 502 upstream?The service behind the API didn't answer. Retry with backoff and check status.clatterlabs.com if it continues.Troubleshooting
- What should I do about 503 unavailable?The key couldn't be checked right now. Retry with backoff; it's usually brief.Troubleshooting
Still need help?
Tried the steps above and still stuck? Email us. We usually reply within the first hour, and always within 24 hours. A full support team is with you.
Infrastructure questions, or permanent deletion of your data
infrastructure@clatterlabs.xyzFor deleting your whole account or the data of one service.