Handling Errors

INFO

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 Code	Description
200 - OK	No error, request operation ran as expected.
400 - Bad Request	Server rejects to process request further, most often caused by missing required parameter, incorrect data type, or malformed body format
401 - Unauthorized	No valid API key found on Authorization header. See Authentication
403 - Forbidden	Provided API key doesn't have enough permission to perform the request.
404 - Not Found	Requested resource for operation doesn't exist.
409 - Conflict	Request sent conflicted with another request (mostly caused by reusing Idempotency-Key). See Request Idempotency
412 - Precondition Failed	Request sent doesn't meet the specified precondition. Usually returned when requesting country-specific endpoints using different country entity.
413 - Request Entity Too Large	Request 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 Type	Request doesn't use specified resource body format or currently missing/having a malformed Content-Type header.
500 - Internal Server Error	Something 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:

Property	Type	Description
type	string	A short string that identifies the error. See: Error Types
code	string?	A more specific error description, not always present. See: Error Codes
message	string	A 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

Example

4xx Errors

400 - Missing Required Property

{
  "error": {
    "type": "invalid_request_error",
    "code": "property_missing",
    "message": "Request property \"company_country\" missing. Please refer to https://docs.zetl.com/embedded/references/customer.html for more information."
  }
}

404 - Unknown URL

{
  "error": {
    "type": "invalid_request_error",
    "code": "url_invalid",
    "message": "Request URL (GET: /v1/random_url) unrecognized. Please refer to https://docs.zetl.com/ for more information."
  }
}

415 - Unsupported Media Type

{
  "error": {
    "type": "invalid_request_error",
    "code": "content_type_invalid",
    "message": "Request must be sent as multipart/form-data. Please refer to https://docs.zetl.com/embedded/references/kyc.html for more information."
  }
}

5xx Errors

500 - Zetl Internal Error

{
  "error": {
    "type": "api_error",
    "message": "Something went wrong on our side. Please try again later."
  }
}

Error Types

Type	Description
api_error	This indicate any issue that is not specified further below and ver rarely occurred.
invalid_request_error	The 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.

Code	Description
url_invalid	The request URL is invalid.
body_invalid	The request body is empty or a malformed JSON object.
resource_not_found	The requested resource doesn't exist.
resource_already_exists	The requested resource already exist.
content_type_invalid	The request Content-Type header is invalid or missing (assumed text/plain).
idempotency_key_in_use	The request uses an idempotency key that is currently in use. See Request Idempotency
idempotency_key_invalid	The request Idempotency-Key header value is invalid. See Request Idempotency
validation_invalid	The request body/part validation general failure.
property_missing	The request is missing one or more required parameters. Add these and try again.
property_unknown	The request includes one or more unknown parameters. Remove these and try again.
property_invalid	The 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.