Skip to main content
Docs

Documentation

Everything you need to integrate CompanyLens into your application or AI agent.

API troubleshooting

Every error response follows the same shape — start by reading the code and message fields:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Daily request quota exceeded. Resets at 00:00 UTC.",
    "correlationId": "req_01j8x4k2m9n..."
  }
}

The correlationId appears on every response — success or error. Include it in any support request so we can locate the exact request in logs immediately.

Common problems

401

Unauthorised — missing or invalid API key

Check that your request includes the Authorization: Bearer YOUR_API_KEY header with the correct prefix. If the key was recently rotated or revoked, generate a new one in your dashboard.

403

Forbidden — endpoint not available on your plan

Your current plan doesn't include the endpoint you're calling. Check the pricing page to see which endpoints are available at each tier. The free tier covers search and basic company lookup.

400

Bad request — invalid parameter

Read the message field in the error response — it names the specific parameter that failed. Common causes: q must be at least 2 characters; pageSize max is 100; jurisdiction codes must appear in the supported list.

404

Not found — entity doesn't exist in this jurisdiction

The company or person ID you provided doesn't exist in the given jurisdiction. Confirm the jurisdiction code is correct — for example, UK companies use gb, not uk. The ID may also have changed if the company was dissolved and re-registered.

429

Rate limited — monthly or daily quota exceeded

Check the Retry-After response header — it gives the number of seconds before your quota resets. Call GET /v1/usage to see your remaining allowance. Daily limits reset at 00:00 UTC; monthly limits reset on your billing date. Upgrade your plan →

500 / 503

Server error — safe to retry

These are transient errors on our side. Both are safe to retry with exponential backoff. For 503s, wait at least 30 seconds before retrying — the upstream registry may be briefly unavailable. If you contact support, include the correlationId from the error response so we can trace the request.

Error code reference

StatusCodeWhen it happens
400INVALID_PARAMETERA query parameter has an invalid value
400INVALID_JURISDICTIONJurisdiction code not in the supported list
401UNAUTHORIZEDAPI key missing, malformed, or missing the Bearer prefix
401KEY_REVOKEDAPI key has been rotated or explicitly revoked
403FORBIDDENYour plan doesn't include this endpoint
404NOT_FOUNDEntity ID doesn't exist in this jurisdiction
422VALIDATION_ERRORRequest body failed validation (batch endpoint)
429RATE_LIMITEDMonthly or daily quota exceeded
500INTERNAL_ERRORServer error — safe to retry with exponential backoff
503REGISTRY_UNAVAILABLEUpstream registry temporarily unreachable — retry after 30 s

Retry strategy

StatusStrategy
429Wait for the value in the Retry-After header (seconds), then retry
500Retry with exponential backoff — start at 1 s, double each attempt, cap at 60 s
503Wait 30 seconds, then retry
4xx (others)Do not retry — fix the request first

Still stuck?

Email [email protected] with the correlationId from the failing response, the endpoint you called, and the request parameters. This lets us find the exact request in logs immediately.