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.
Markdown source: /docs/errors.md