CartrouteHow does the Cartroute API report errors?
Every API error is an RFC 9457 application/problem+json body with a stable machine code, an HTTP status, a human detail and the request_id. Branch on code, never on the wording of detail. No error is ever charged.
What does an error body look like?
{
"type": "https://cart-route.com/docs/errors#validation_error",
"title": "Request validation failed",
"status": 422,
"detail": "`limit` must be an integer between 1 and 25.",
"code": "validation_error",
"instance": "/api/v1/search?q=tv&limit=500",
"request_id": "req_2m9x1q0a4b8c7f3k",
"param": "limit"
}
Extra fields appear where they help: param and sometimes valid_values for validation errors, credits_remaining and top_up_url for credit errors, retry_after_seconds for rate limits.
Which error codes exist and what should an agent do?
| HTTP | code | Meaning | Agent action | Retry? |
|---|---|---|---|---|
| 401 | unauthorized | Key missing, malformed or revoked. | Stop; ask the user for a valid key. | No |
| 402 | insufficient_credits | Balance below the call's cost. | Stop; tell the user, cite top_up_url and any verify_email_bonus. | No |
| 403 | account_suspended | Account suspended by an operator. | Stop; contact [email protected]. | No |
| 403 | forbidden | Not allowed for this key. | Stop. | No |
| 404 | not_found | Unknown product or path. | Search instead, or check the id. | No |
| 405 | method_not_allowed | Wrong HTTP method. | Fix the request. | No |
| 422 | validation_error | A parameter is invalid; param names it. | Fix that parameter and resend. | After fixing |
| 429 | rate_limited | Too many requests in the window. | Wait Retry-After seconds. | Yes |
| 500 | internal_error | Failure on our side. | Retry with backoff and the same Idempotency-Key. | Yes |
How do errors appear over MCP?
A tool that fails returns a normal result with isError: true, and its JSON content carries the same code values, for example {"error": "...", "code": "insufficient_credits", "credits_remaining": 0}. That lets the model read the problem and explain it. Protocol-level problems (unknown method, malformed JSON) use JSON-RPC error codes: -32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32001 invalid API key.
What about web pages?
Pages requested as JSON return {"object": "error", "code": ..., "detail": ...} with the matching status, for example 404 not_found or 402 preview_limit_reached when an anonymous visitor exceeds five searches a day.