Errors & limits
Errors are JSON with a stable code:
{ "error": "country_not_entitled" }
Error codes
| STATUS | CODE | WHEN |
|---|---|---|
| 400 | missing_query | Search without q or structured params. |
| 400 | conflicting_parameters | Search mixing q with structured params. |
| 400 | missing_country | registrationNumber or name without country. |
| 400 | missing_entity_address | Investigate without entityId, country+registrationNumber, or registry+registryRef. |
| 422 | unsupported_lookup_for_country | That country's registry has no registration-number lookup yet. |
| 401 | missing_or_unknown_api_key | No key, a key we don't recognize, or a revoked key. |
| 402 | quota_exceeded | Your plan's monthly investigation allowance is used up. Investigations from the app count too. Upgrade to run more. |
| 403 | country_not_entitled | The entity belongs to a country outside your key. On search this arrives as a 200 with a note instead. |
| 404 | unknown_id | Id prefix matches no connected registry. |
| 404 | not_found | No record behind the id. |
| 405 | method_not_allowed | Wrong HTTP method. |
| 429 | rate_limit_exceeded | Too many requests — back off and retry. |
Limits
Your plan sets three limits, shown under Account → API keys: monthly investigations (shared between the app, the API and MCP), exploration steps per investigation, and requests per minute per key. If you're building for volume, talk to us about higher limits.
Retries
429 — back off and retry. 5xx — retry once, then report it. Investigations are safe to re-run; they are stateless.