BC Data docsErrors
The error shape and every error code the BC Data REST API and MCP server return.
Shape
Every REST error is JSON with an HTTP status:
{ "error": { "code": "rate_limited", "message": "Too many requests.", "retry_after_seconds": 41, "window": "minute" } }A tool that cannot answer returns available: false, an error with a code and a message, and citations: [], the same as over MCP:
{ "available": false, "error": { "code": "not_found", "message": "No record with that ref." }, "citations": [] }Codes
| Code | HTTP | Meaning |
|---|---|---|
unauthorized | 401 | No key, or the key is wrong or revoked. |
forbidden_origin | 403 | An account request came from a website that is not allowed. |
invalid_request | 400 | The request body is not valid. |
invalid_params | 400 | A tool's arguments failed validation. The message says which. |
not_found | 404 | No such tool, record or key. |
rate_limited | 429 | Over that key's allowance. Wait retry-after seconds. window is minute or day. |
key_limit | 409 | You already have 5 active keys. |
already_requested | 429 | You asked for higher limits in the last 24 hours. |
unavailable | 502 | The government source could not be reached. |
mail_failed | 502 | The email could not be sent. Nothing was counted. Try again. |
kill_switch | 503 | The service is switched off. |
limits_unavailable | 503 | The counters could not be read, so the service refused. |
budget_exhausted | 503 | The daily budget for the whole service is used up. |
internal | 500 | Something broke on our side. |
Some tools return their own refusal codes. Each keeps its meaning and an HTTP status in the 4xx range, except a source that could not be fetched, which is 502.
Over MCP
Without a valid key, /mcp answers HTTP 401 with WWW-Authenticate: Bearer realm="bc-data" and a JSON-RPC error with code -32001 that says where to sign up. This applies to initialize and tools/list too.