api errors and status codes
the api returns predictable error statuses so agents can decide whether to retry, ask for a key, ask for an upgrade, or change the request.
quick answer
treat the status code as the first routing signal, then read the error field for the exact reason.
use this for
- building resilient api clients
- teaching an agent when to retry
- debugging mcp tool failures
steps
- read the http status code.
- read the json error or error code.
- fix request shape errors before retrying.
- refresh or replace the key for authentication errors.
- send the user to billing for plan-gated errors.
- back off on rate-limit errors.
details to know
- 400 means the request is malformed, incomplete, or ambiguous.
- 401 means the request is not authenticated.
- 402 means the account plan does not allow the requested paid action.
- 403 means the key or user is authenticated but not allowed.
- 404 means the requested resource was not found or not owned by the user.
- 429 means a rate limit or quota stopped the request.
limits and edge cases
- do not blindly retry 400, 401, 402, or 403 responses.
- a 404 should not reveal whether another user's private resource exists.
- agents should show the user the next safe action, not the raw stack trace.
ready to use the product instead of reading about it?
open app