Error responses you can act on

Most API errors tell you that something failed. Good errors say what to do next. We treat every error response as part of the interface.

The shape

Errors are application/problem+json, following RFC 9457:

{
  "type": "https://corpoapi.com/errors/free_tier_exhausted",
  "title": "Free tier exhausted",
  "status": 402,
  "code": "free_tier_exhausted",
  "detail": "The 100 free starter calls are used up. Billing is not open yet.",
  "retryable": false
}

The code is stable. Branch on it, not on the human-readable detail, which can change wording.

Codes worth branching on

• invalid_identifier: the number you passed failed the registry's check digit. Fix the input, do not retry.
• company_not_found: no company matched. Free, and not retryable without a different input.
• free_tier_exhausted: the starter allowance is used up and billing is not open yet. Retrying will not help.
• rate_limited: back off using Retry-After.
• registry_unavailable / registry_budget_exhausted: the upstream register is down or capped. A cached copy is served when we have one.

Retries

Retries are the norm in production, so two things keep them safe. The same company is billed at most once per UTC day, so a retry that re-reads a company does not bill it twice. And rate limits are reported on every response through RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, so a well-behaved client can pace itself instead of discovering the limit by hitting it.