HTTP status codes, rate-limit headers, and Probara-specific error identifiers. All errors return JSON with a consistent shape.
{
"error": {
"code": "rate_limit_exceeded",
"message": "You have exceeded your rate limit. Retry after 12 seconds.",
"status": 429,
"request_id": "req_01HXYZ",
"retry_after": 12
}
}message field for which field failed validation. Authorization: Bearer <key> header.
Rate limits are applied per API key. When you exceed your limit, you receive a
429 response. The response includes headers telling you when to retry.
X-RateLimit-Limit Maximum requests allowed in the current window. X-RateLimit-Remaining Requests remaining in the current window. X-RateLimit-Reset Unix timestamp when the window resets. Retry-After Seconds to wait before retrying. Present only on 429 responses. # Exponential backoff with jitter
base = 1 # seconds
max_wait = 32
attempt = 0
while attempt < 5:
response = call_api()
if response.status != 429:
break
wait = min(base * (2 ** attempt) + random(0, 1), max_wait)
sleep(wait)
attempt += 1
The error.code field in the response body carries a machine-readable
identifier. Use this to differentiate error types without string-matching on message.
invalid_api_key 401 API key format is invalid or the key does not exist. api_key_revoked 401 The API key has been revoked. Generate a new key from your account. rate_limit_exceeded 429 Per-minute request limit reached for your plan. Check Retry-After header. daily_limit_reached 429 Free tier daily card limit reached. Resets at midnight UTC or upgrade your plan. evidence_coverage_insufficient 404 The requested ingredient is outside current coverage. See /coverage for covered ingredients. ingredient_not_found 404 Ingredient name did not match any known compound. Check spelling or use the canonical name. attestation_failed 500 HMAC signing failed internally. The card was not issued. Retry; if persistent, contact support.