Skip to main content
Docs

Documentation

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

Errors

All errors follow a consistent shape regardless of the endpoint.

Error shape

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

Error codes

HTTP statusCodeWhen it happens
400INVALID_PARAMETERA query parameter has an invalid value (e.g. pageSize over 100, q under 2 characters)
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 — see pricing
404NOT_FOUNDEntity ID doesn't exist in this jurisdiction
422VALIDATION_ERRORRequest body failed validation (batch endpoint)
429RATE_LIMITEDMonthly or daily quota exceeded — see rate limits
500INTERNAL_ERRORServer error — safe to retry; include correlationId when contacting support
503REGISTRY_UNAVAILABLEUpstream registry temporarily unreachable — retry after 30 seconds

The correlationId field

Every response — success or error — includes a correlationId. Include it in any support request: it allows us to find your specific request in logs immediately, regardless of when it occurred.

// Success response
{
  "results": [...],
  "correlationId": "req_01j8x4k2m9n..."
}

// Error response
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Entity gb-99999999 not found.",
    "correlationId": "req_01j8x4k2m9n..."
  }
}

Retrying requests

StatusStrategy
429Back off and retry after the value in the Retry-After header (seconds)
500Safe to retry with exponential backoff
503Retry after 30 seconds
4xx (others)Do not retry — the request itself is invalid; fix it first