Errors¶

ApiCrate returns structured errors for both the REST API and the MCP server. The format differs between the two interfaces, but the underlying error conditions are the same.

REST API Errors¶

REST API errors are returned as JSON objects with a detail field describing what went wrong. The HTTP status code indicates the error category.

{
  "detail": "Postal code not found: 99999 in US"
}

The following table lists the most common HTTP status codes:

Code	Meaning	Description
`400`	Bad Request	The request is malformed or contains invalid parameters.
`401`	Unauthorized	The API key is missing, invalid, or expired. See Authentication.
`404`	Not Found	The requested resource does not exist (e.g., unknown country code, postal code not in database).
`422`	Validation Error	One or more parameters failed validation (e.g., latitude out of range, missing required field).
`429`	Too Many Requests	Your quota for the current window has been exhausted. Wait for the reset or upgrade your plan.
`500`	Internal Server Error	An unexpected error occurred on the server. Retry the request or contact support if it persists.
`503`	Service Unavailable	The service is temporarily unavailable (e.g., during maintenance or a backing-service outage). Retry after a short delay.

MCP Errors¶

MCP tool errors are returned as ToolError responses with isError set to true. The error message is a plain-text string in the content block — there is no JSON body to parse.

{
  "type": "tool_result",
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Postal code not found: 99999 in US"
    }
  ]
}

Your AI client will see this error and can retry with corrected parameters or report the issue back to you.

Common MCP error types:

Not found — the requested resource does not exist in the database (e.g., Country not found: ZZ, Postal code not found: 00000 in US).
Validation error — one or more parameters are invalid or out of range (e.g., Invalid lat: 999. Must be between -90 and 90.).
Quota exceeded — your credit allowance for the current window has been exhausted (e.g., Quota exceeded. Limit: 1000, resets at: 1711497600).
Unauthorized — the X-API-Key header is missing, invalid, or expired.

Rate Limiting¶

ApiCrate uses a credit-based quota system for rate limiting. The following headers are included in every REST API response so you can monitor your usage in real time:

Header	Description
`X-Quota-Limit`	The total number of credits available in your current billing window.
`X-Quota-Remaining`	The number of credits remaining before the next reset.
`X-Quota-Reset`	Unix timestamp indicating when your quota resets.

When your remaining credits reach zero, subsequent requests return HTTP 429 Too Many Requests (REST API) or a quota-exceeded ToolError (MCP).

For details on how MCP credits are consumed and how the billing system works, see Credits.