# Errors

Every error is JSON with `success: false` and an `error` object: `code` (stable identifier), `message` (what went wrong and how to fix it), `field` (offending parameter, when applicable), `hint` (allowed values or example), `retryable`, and `retry_after_seconds` when retryable.

| HTTP | code | Meaning | Fix |
| --- | --- | --- | --- |
| 400 | MISSING_PARAMETER | A required input is absent | Supply the field named in `field` |
| 400 | INVALID_JSON | POST body is not valid JSON | Send `{"inputs": {…}}` |
| 400 | INVALID_REQUEST | Malformed request (e.g. JSON-RPC shape) | See message |
| 404 | UNKNOWN_CALCULATOR | No calculator with that id | Use `/api/v1/search` |
| 404 | NOT_FOUND | Unknown route | See `/api/v1` |
| 405 | METHOD_NOT_ALLOWED | Wrong HTTP method | Use the method listed in OpenAPI |
| 422 | INVALID_PARAMETER | Wrong type/format | Follow the type in the schema |
| 422 | OUT_OF_RANGE | Value outside the allowed range | Respect min/max in `hint` |
| 422 | INVALID_ENUM_VALUE | Not one of the allowed values | Use a listed value |
| 422 | INVALID_DATE | Not a valid ISO date | Use YYYY-MM-DD |
| 422 | INVALID_LIST | List malformed or wrong length | Comma-separated numbers |
| 422 | UNKNOWN_UNIT | Unit symbol not recognised or quantities differ | See `/api/v1/units` |
| 422 | CALCULATION_ERROR | Inputs valid but mathematically impossible (e.g. triangle inequality) | Read `message` |
| 429 | RATE_LIMITED | Too many requests | Wait `retry_after_seconds` / `Retry-After` header |
| 500 | INTERNAL_ERROR | Unexpected failure | Retry once; report if persistent |

MCP: input/validation failures are returned as tool results with `isError: true` (not JSON-RPC protocol errors), so the model can correct the call. A2A: failures produce a task in state `failed` with the error in `status.message`.