Skip to content
API Documentation

Error Handling

Learn which status codes the Worklayer API returns and how to read the error response body.

The Worklayer API uses HTTP status codes to tell you whether a request succeeded. A 2xx status code means success. A 4xx status code means the request is invalid, is not allowed, or conflicts with the current state of a resource. A 5xx status code means something went wrong on the Worklayer side.

Every error response from the API itself has a JSON body in the Problem Details format, served with the application/problem+json content type. Two cases are different and are described below: rate limit responses and the OAuth token endpoint.

Status codes
Status codeMeaning
400The request is malformed, a path or query parameter is invalid, or the payload failed validation. The body usually explains what is wrong.
401The Authorization header is missing, or the bearer token is invalid or expired. See Authentication.
403The token is valid, but your API client does not have permission to perform this action, or the resource belongs to a different workspace.
404The resource was not found. This is also returned when the resource exists but is not visible to your workspace.
409The request conflicts with the current state of the resource. For example, OCR processing has already started for a document, or the job is closed.
429Your IP address exceeded a rate limit. See Rate Limits.
500An unexpected error happened on the Worklayer side. Retry with backoff. If the error persists, contact support and include the trace_id from the response body.
503A service the API depends on did not respond. Retry with backoff.

The documentation page for each endpoint lists the status codes that endpoint can return and the reason for each one.

The error response body

All error responses returned by the API share the same top-level properties. Some properties are omitted from the body when they do not apply.

type
•
string

A URL that identifies the status code, in the form https://httpstatuses.io/{status}.

title
•
string

A short, human-readable summary of the error. For most errors, this is the standard reason phrase of the status code, such as Not Found. For validation errors, it is One or more validation errors occurred.

status
•
integer

The HTTP status code, repeated in the body.

detail
•
string

A human-readable explanation specific to this failure, such as Document is not ready for OCR processing. Present when the endpoint has a specific reason to report. Use it only for logging and debugging. The text can change without notice, so do not branch your code on it.

errors
•
object

Present only on 400 validation errors. Each key maps to an array of one or more messages. The key is either the name of the invalid field or, when the error is not tied to a single field, a generic key such as error_0 or error_1.

trace_id
•
string

The identifier of the distributed trace for this request. Include it when you contact support about a failed request.

request_id
•
string

The identifier the API server assigned to this request.

request_path
•
string

The path of the request that failed.

Sample 404 response

json
Copied
1{
2  "type": "https://httpstatuses.io/404",
3  "title": "Not Found",
4  "status": 404,
5  "detail": "Document not found",
6  "trace_id": "00-9a1f2c8d5e6b4a3f9c0d1e2f3a4b5c6d-4e5f6a7b8c9d0e1f-01",
7  "request_id": "0HN7G2K3L4M5N:00000007",
8  "request_path": "/v1.0/ocr/start"
9}

Sample 400 validation response

json
Copied
1{
2  "type": "https://httpstatuses.io/400",
3  "title": "One or more validation errors occurred.",
4  "status": 400,
5  "errors": {
6    "error_0": ["Job ID is required"],
7    "error_1": ["An empty UUID is not a valid user ID"]
8  },
9  "trace_id": "00-9a1f2c8d5e6b4a3f9c0d1e2f3a4b5c6d-4e5f6a7b8c9d0e1f-01",
10  "request_id": "0HN7G2K3L4M5N:00000008",
11  "request_path": "/v1.0/jobs"
12}

Sample 401 response

json
Copied
1{
2  "type": "https://httpstatuses.io/401",
3  "title": "Unauthorized",
4  "status": 401,
5  "trace_id": "00-9a1f2c8d5e6b4a3f9c0d1e2f3a4b5c6d-4e5f6a7b8c9d0e1f-01",
6  "request_id": "0HN7G2K3L4M5N:00000009",
7  "request_path": "/v1.0/members"
8}

Exceptions to the standard shape

Rate limit responses

Rate limits are enforced at the network edge, before a request reaches the API. A 429 response therefore does not have a Problem Details body. Rely on the status code only, wait, and retry with backoff. See Rate Limits for the limits that apply.

The OAuth token endpoint

The /oauth/token endpoint follows the OAuth 2.0 error format from RFC 6749 section 5.2 instead of Problem Details. Its error body has an error code and an error_description. See Authentication for the list of error codes.

Handling errors in your integration
  • Branch on the status code. The detail text is for people, not for programs.
  • Retry 429, 500, and 503 responses with exponential backoff. Do not retry other 4xx responses without changing the request.
  • Log the trace_id and request_id of failed requests, and include them when you contact support.
  • Read the error list on each endpoint's page for the reasons that are specific to that endpoint.

Next steps

Last updated on October 2, 2026
Privacy PolicyTerms & Conditions© 2026 Taxfyle