{
  "object": "doc",
  "title": "How does the Cartroute API report errors?",
  "description": "RFC 9457 problem+json, every error code, and what an agent should do.",
  "section": "Concepts",
  "url": "https://cart-route.com/docs/errors",
  "updated": "2026-09-23",
  "prev": "https://cart-route.com/docs/objects",
  "next": "https://cart-route.com/docs/rate-limits",
  "text": "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.\n\n## What does an error body look like?\n\n```\n{\n  \"type\": \"https://cart-route.com/docs/errors#validation_error\",\n  \"title\": \"Request validation failed\",\n  \"status\": 422,\n  \"detail\": \"`limit` must be an integer between 1 and 25.\",\n  \"code\": \"validation_error\",\n  \"instance\": \"/api/v1/search?q=tv&limit=500\",\n  \"request_id\": \"req_2m9x1q0a4b8c7f3k\",\n  \"param\": \"limit\"\n}\n```\n\nExtra 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.\n\n## Which error codes exist and what should an agent do?\n\n| HTTP | code | Meaning | Agent action | Retry? |\n\n| 401 | `unauthorized` | Key missing, malformed or revoked. | Stop; ask the user for a valid key. | No |\n\n| 402 | `insufficient_credits` | Balance below the call's cost. | Stop; tell the user, cite `top_up_url` and any `verify_email_bonus`. | No |\n\n| 403 | `account_suspended` | Account suspended by an operator. | Stop; contact support@cart-route.com. | No |\n\n| 403 | `forbidden` | Not allowed for this key. | Stop. | No |\n\n| 404 | `not_found` | Unknown product or path. | Search instead, or check the id. | No |\n\n| 405 | `method_not_allowed` | Wrong HTTP method. | Fix the request. | No |\n\n| 422 | `validation_error` | A parameter is invalid; `param` names it. | Fix that parameter and resend. | After fixing |\n\n| 429 | `rate_limited` | Too many requests in the window. | Wait `Retry-After` seconds. | Yes |\n\n| 500 | `internal_error` | Failure on our side. | Retry with backoff and the same `Idempotency-Key`. | Yes |\n\n## How do errors appear over MCP?\n\nA 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.\n\n## What about web pages?\n\nPages 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."
}