Errors

Stable error codes and the error envelope returned by every failed call.

Every error response uses an error wrapper:

{ "error": { "code": "validation_error", "message": "Provide at least one discovery filter." } }

Some validation errors include a details array:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request payload.",
    "details": [
      { "code": "invalid_type", "expected": "string", "received": "undefined", "path": ["linkedin_url"], "message": "Required" }
    ]
  }
}

Error codes

`code`	HTTP	Meaning
`unauthorized`	401	Missing or invalid API key.
`validation_error`	400	Request body or query params failed validation.
`lead_not_found`	404	Referenced lead does not exist in this workspace.
`not_implemented`	501	Endpoint exists but the underlying capability is not available for this request.
`rate_limit_exceeded`	429	API key exceeded its configured rate limit.
`insufficient_credits`	402	Workspace does not have enough enrichment credits for the requested operation.
`service_error`	500	Unexpected service failure. Retry with backoff.

Handling errors

Branch on HTTP status first, then on error.code for typed handling.
Surface error.message in user-facing logs.
Capture x-request-id from the response headers and include it in any support ticket.
Retry service_error (500) and rate_limit_exceeded (429) with exponential backoff.
Stop and prompt the user for action on unauthorized (401) and insufficient_credits (402): these will not resolve on retry.