Skip to main content

​
Error Codes

Every error response from the Zenoo API includes a machine-readable error code, a human-readable message, and a unique request ID.

​
Response format

{
  "error": "VALIDATION_ERROR",
  "message": "Missing required field: company_name",
  "request_id": "req-a1b2c3d4"
}
FieldDescription
errorMachine-readable error code. Use this for programmatic error handling.
messageHuman-readable description. Log this, but do not display it to end users.
request_idUnique identifier for the request. Include this in support tickets.
Always log the request_id from every error response. It is essential for correlating issues with Zenoo support.

​
Error code reference

Error CodeHTTP StatusDescriptionRetryableRecommended Action
VALIDATION_ERROR400Missing or invalid required fieldsNoFix the request payload and resubmit
INVALID_JSON400Request body is not valid JSONNoCheck for syntax errors in the JSON body
UNAUTHORIZED401Missing or invalid API keyNoVerify the X-API-KEY header value
FORBIDDEN403API key does not have access to this projectNoContact Zenoo support for access
NOT_FOUND404Invalid project hash, endpoint, or resourceNoVerify the URL, project hash, and resource ID
TOKEN_EXPIRED404Pull token has expiredNoInitiate a new verification to get fresh tokens
PROCESSING204Results still processing (pull endpoint only)YesRetry per polling strategy in Sync vs Async
RATE_LIMITED429Too many requestsYesWait for the duration in the Retry-After header
INTERNAL_ERROR500Unexpected server errorYesRetry with exponential backoff
PROVIDER_ERROR502Upstream provider failure (registry, screening)YesRetry with exponential backoff
SERVICE_UNAVAILABLE503Zenoo service temporarily unavailableYesRetry after 30 seconds

​
Examples

Returned when the request is missing required fields or contains invalid values.
{
  "error": "VALIDATION_ERROR",
  "message": "Missing required field: company_name",
  "request_id": "req-7f3a2b1c"
}

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid country code: UK. Use ISO 3166-1 alpha-2 (GB).",
  "request_id": "req-8e4d3c2a"
}
Returned when the request body cannot be parsed as JSON.
{
  "error": "INVALID_JSON",
  "message": "Unexpected token at position 42",
  "request_id": "req-9a5e4d3b"
}
Returned when the X-API-KEY header is missing or contains an invalid key.
{
  "error": "UNAUTHORIZED",
  "message": "Invalid API key",
  "request_id": "req-1b6f5e4c"
}
Returned when the API key is valid but does not have access to the requested project.
{
  "error": "FORBIDDEN",
  "message": "API key does not have access to project abc123",
  "request_id": "req-2c7a6f5d"
}
Returned when the project hash, endpoint, or resource does not exist.
{
  "error": "NOT_FOUND",
  "message": "Project not found: invalid-hash",
  "request_id": "req-3d8b7a6e"
}
Returned when a pull token has expired. Pull tokens are valid for 30 days after results become available. Start tokens (verification URLs) expire after 24 hours.
{
  "error": "TOKEN_EXPIRED",
  "message": "Pull token has expired. Initiate a new verification.",
  "request_id": "req-4e9c8b7f"
}
Returned when request volume exceeds your project’s rate limit. The Retry-After header tells you how many seconds to wait.
{
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded. Retry after 60 seconds.",
  "request_id": "req-5f0d9c8a"
}
Response headers:
Retry-After: 60
Returned for unexpected server errors. These are transient and should be retried.
{
  "error": "INTERNAL_ERROR",
  "message": "An unexpected error occurred. Please retry.",
  "request_id": "req-6a1e0d9b"
}
Returned when an upstream verification provider (registry, screening) fails. Zenoo automatically retries provider failures for async flows. For sync flows, retry the request.
{
  "error": "PROVIDER_ERROR",
  "message": "Upstream provider temporarily unavailable",
  "request_id": "req-7b2f1e0c"
}
Returned when the Zenoo service is temporarily unavailable (maintenance, capacity limits). Retry after 30 seconds.
{
  "error": "SERVICE_UNAVAILABLE",
  "message": "Service temporarily unavailable. Please retry.",
  "request_id": "req-8c3a2f1d"
}

​
Retry logic

Only retry errors marked as retryable in the table above. For 4xx errors, fix the request before resubmitting.
Use the following exponential backoff schedule for retryable errors:
Attempt 1: Immediate
Attempt 2: Wait 5 seconds
Attempt 3: Wait 25 seconds
Attempt 4: Wait 60 seconds
Maximum: 4 attempts
For RATE_LIMITED (429), always use the Retry-After header value instead of the default backoff schedule. For detailed retry implementation, see Error Handling.

​
Next steps