Error Handling
Getting Started

Error Handling

200 OK Request successful.
400 Bad Request Invalid parameters — e.g. a search with neither q nor filters.
401 Unauthorized API key or Bearer token is missing or invalid.
402 Payment Required Not enough credits for this request.
403 Forbidden Missing subscription (fetch-person), unverified email, or blocked account.
404 Not Found No matching company found — no credits are charged.
429 Too Many Requests Rate limit exceeded.
500 Server Error Internal server error.

Error Response Formats

Errors come back as JSON. Billing-related errors carry a meta object whose request_credit_cost field always reflects what was actually charged — 0 for failed requests, except the AI surcharge:

402 — Not enough credits

{
  "meta": {
    "message": "Insufficient credits to perform this operation.",
    "request_credit_cost": 25,
    "credits_remaining": 3
  }
}

404 — Company not found

{
  "detail": [
    {
      "type": "not_found",
      "loc": ["path", "q"],
      "msg": "Organization that matches 'Example GmbH' does not exist",
      "input": {"q": "Example GmbH"}
    }
  ],
  "meta": {
    "request_credit_cost": 0,
    "credits_remaining": 1250
  }
}

403 — Subscription required (fetch-person)

{
  "error": "subscription_required",
  "meta": {
    "message": "fetch-person requires an active Plus, Pro, or Max subscription.",
    "required_plans": ["plus", "pro", "max"],
    "request_credit_cost": 0,
    "credits_remaining": 1250
  }
}

401 — Unauthorized

{
  "error": "Unauthorized: Missing or invalid authentication. Please provide a valid API key (via x-api-key header or api_key parameter) or Bearer token."
}