Skip to content

Handling Errors


This documentation is work in progress and subject to change. If you have any questions or feedback, please reach out to us via Support.

Zetl API uses standard HTTP status codes to indicate whether a request succeeded or failed. In cases of error, the response body will contain additional information about the specifics.

Response HTTP Status Code Summary

Status CodeDescription
200 - OKNo error, request operation ran as expected.
400 - Bad RequestServer rejects to process request further, most often caused by missing required parameter, incorrect data type, or malformed body format
401 - UnauthorizedNo valid API key found on Authorization header. See Authentication
403 - ForbiddenProvided API key doesn't have enough permission to perform the request.
404 - Not FoundRequested resource for operation doesn't exist.
409 - ConflictRequest sent conflicted with another request (mostly caused by reusing Idempotency-Key). See Request Idempotency
412 - Precondition FailedRequest sent doesn't meet the specified precondition. Usually returned when requesting country-specific endpoints using different country entity.
413 - Request Entity Too LargeRequest entity is too large. Our system will preemptively reject request with total parts larger than 100MiB for multipart/form-data endpoints and 3 MiB body for json body.
415 - Unsupported Media TypeRequest doesn't use specified resource body format or currently missing/having a malformed Content-Type header.
500 - Internal Server ErrorSomething went wrong on our side (these rarely occurred).

Error Response Body Properties

On request failure we will send an error object inside response body. The error object contains the following properties:

typestringA short string that identifies the error. See: Error Types
codestring?A more specific error description, not always present. See: Error Codes
messagestringA human readable message that describes the error and sometimes contain documentation reference URL

Some 4xx errors could be handled programmatically. In these cases, the API will return a code property in the error object. The code property is a short string that identifies the error. See: Error Codes


4xx Errors
  "error": {
    "type": "invalid_request_error",
    "code": "property_missing",
    "message": "Request property \"company_country\" missing. Please refer to for more information."
  "error": {
    "type": "invalid_request_error",
    "code": "url_invalid",
    "message": "Request URL (GET: /v1/random_url) unrecognized. Please refer to for more information."
  "error": {
    "type": "invalid_request_error",
    "code": "content_type_invalid",
    "message": "Request must be sent as multipart/form-data. Please refer to for more information."
5xx Errors
  "error": {
    "type": "api_error",
    "message": "Something went wrong on our side. Please try again later."

Error Types

api_errorThis indicate any issue that is not specified further below and ver rarely occurred.
invalid_request_errorThe request is missing a required parameter, includes an invalid parameter,

Error Codes

These are a non-exhaustive list of generic error codes that we may return for all resource types. For resource-specific error codes it will be specified in its specific resource documentation.

url_invalidThe request URL is invalid.
body_invalidThe request body is empty or a malformed JSON object.
resource_not_foundThe requested resource doesn't exist.
resource_already_existsThe requested resource already exist.
content_type_invalidThe request Content-Type header is invalid or missing (assumed text/plain).
idempotency_key_in_useThe request uses an idempotency key that is currently in use. See Request Idempotency
idempotency_key_invalidThe request Idempotency-Key header value is invalid. See Request Idempotency
validation_invalidThe request body/part validation general failure.
property_missingThe request is missing one or more required parameters. Add these and try again.
property_unknownThe request includes one or more unknown parameters. Remove these and try again.
property_invalidThe request includes one or more invalid parameters value. Use the correct data type and try again.

Request Id

All API responses include a unique identifier X-Zetl-Request-Id. We use this request id to keep track any request operation throughout our system for monitoring and logging purpose.

Please include this ID in all support requests when relevant.