Error Response Schema

When a request fails, the Worklio API returns an HTTP status code and, in almost every case, a JSON error body. This page covers the error format for /wep/... endpoints (API version 2.0), the status codes you can receive, and how to handle each one.

Branch on the HTTP status code first. Use code, errorCode and validationErrors in the body for detail.

2xx: success. /wep/... endpoints return the resource itself, with no error envelope.
4xx: the request needs fixing. The cause is authentication, permissions, a missing resource, or invalid input.
5xx: a server-side failure. Retry idempotent requests; report persistent failures.

Every error body is application/json with camelCase property names, with two exceptions: a 401 has no body, and a request to an unknown route returns 404 with no body. For a 401, read the WWW-Authenticate header.

Token requests to /connect/token use a different, OAuth-standard error format. See Token endpoint errors.

Error response format

{
  "status": 0,
  "code": "400",
  "errorCode": "WEP_BadRequest",
  "message": "9/18/2026 - 7:57:40 AM : Filing Status: Value_Required\nAdditional Withholding: Value_Required\nTotal Allowances: Value_Required",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": null
}

Field	Type	Description
`status`	integer	Result status: `0` None, `1` Success, `2` Warning, `3` Error. Errors raised inside an endpoint return `0`. Validation, access and scope errors return `3`. Use the HTTP status code instead of this field.
`code`	string	The HTTP status code as a string (`"400"`, `"403"`, `"404"`, `"500"`), or `"DataValidationError"` for request validation failures.
`errorCode`	string or null	A machine-readable reason, for example `WEP_BadRequest` or `EmployeeHasAnyTimeOffPolicy`. `null` or `""` when no specific reason applies.
`message`	string	Human-readable description. For errors raised inside an endpoint, it starts with a server timestamp: `9/18/2026 - 7:57:40 AM : <message>`. When several problems are found at once, they are listed in one string separated by `\n`.
`stackTrace`	string	Empty in captured responses. Don't depend on it.
`pagination`	object	Present but zeroed on errors. Ignore it.
`validationErrors`	object or null	Set only for request validation failures. Keys are camelCase field names (nested fields use dots, for example `address.zip`). Each value is a list of `[errorCode, message]` pairs.

Prefer errorCode and validationErrors keys over message when your code needs to branch on a specific failure. message is display text, and its wording can change. If you must match on message text, match only the part after the timestamp.

HTTP status codes

Status	Meaning	Body	When it happens
`400 Bad Request`	Invalid input	Error envelope	The request body or parameters fail validation (`code: "DataValidationError"`). A required value is missing (`errorCode: "WEP_BadRequest"`). A business rule rejects the request. The `api-version` header names an unsupported version.
`401 Unauthorized`	Not authenticated	None	The bearer token is missing, expired or invalid. See the `WWW-Authenticate` header.
`403 Forbidden`	Not allowed	Error envelope	The token lacks the `api` scope. The user has no access to the company or employee in the route. An IP restriction applies. The password changed after the token was issued.
`404 Not Found`	Missing resource	Error envelope	The company, employee or other entity in the route doesn't exist or isn't visible to the user. An unknown route returns `404` with no body.
`500 Internal Server Error`	Server failure	Error envelope	An unexpected server error.

Error examples

Field values and message text in the 401, 403, 404 and 500 examples are illustrative.

400: Required value missing

Returned when a required value is missing from the request. The message lists each missing value on its own line. This example is from Employee Tax Setup.

{
  "status": 0,
  "code": "400",
  "errorCode": "WEP_BadRequest",
  "message": "9/18/2026 - 7:57:40 AM : Filing Status: Value_Required\nAdditional Withholding: Value_Required\nTotal Allowances: Value_Required",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": null
}

400: Request validation failed

Returned when the request body or parameters fail model validation, before the endpoint runs. Each entry in validationErrors maps a field name to its [errorCode, message] pairs.

{
  "status": 3,
  "code": "DataValidationError",
  "errorCode": "",
  "message": "One or more validation errors occurred.\r\nFirstName: [The FirstName field is required.]\r\nZip: [Invalid ZIP code format.]",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": {
    "firstName": [["requiredError", "The FirstName field is required."]],
    "zip": [["ZIPFormatError", "Invalid ZIP code format."]]
  }
}

Validation errorCode values include: requiredError, tooLongError, tooShortError, outOfRangeError, stringLengthError, positiveValueError, intValueError, SSNFormatError, FEINFormatError, ZIPFormatError, phoneNumberError, routingNumberError, eMailFormatError, regularExpressionError.

400: Business rule rejected the request

Returned when the input is well-formed but the operation isn't allowed in the current state. This example is from Employee Time Off Policy Setup: an employee can be enrolled in only one policy at a time.

{
  "status": 0,
  "code": "400",
  "errorCode": "EmployeeHasAnyTimeOffPolicy",
  "message": "9/17/2026 - 2:58:52 PM : Active Policy for this Employee Already Exists",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": null
}

400: Unsupported API version

Returned when the api-version or x-api-version header names a version the endpoint doesn't support.

{
  "status": 3,
  "code": "UnsupportedApiVersion",
  "errorCode": "",
  "message": "The HTTP resource that matches the request URI 'https://api.worklio.com/wep/companies/123' does not support the API version '9.0'.",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  }
}

401: Missing, expired or invalid token

There is no body. The reason is in the WWW-Authenticate header.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"
Content-Length: 0

Access tokens expire after 24 hours. See How to Get API Access.

403: No access to the resource

Returned when the token is valid but the user can't access the company or employee in the route.

{
  "status": 3,
  "code": "403",
  "errorCode": "",
  "message": "Access denied.",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  }
}

Other 403 messages:

Access denied due to IP address restriction set. Please contact the admin.
Access denied because the IP address changed. You have authenticated with IP address {authIP}, now your IP address is {requestIP}.
Access denied because your password changed. Please authenticate again.

A token without the api scope also returns 403 with message: "Access denied." and the header WWW-Authenticate: Bearer error="insufficient_scope".

404: Resource not found

{
  "status": 0,
  "code": "404",
  "errorCode": null,
  "message": "10/7/2026 - 2:15:32 PM : Not found.",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": null
}

500: Internal server error

{
  "status": 0,
  "code": "500",
  "errorCode": null,
  "message": "10/7/2026 - 2:15:32 PM : Internal Server Error.",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": null
}

Token endpoint errors

POST https://api.worklio.com/connect/token returns standard OAuth errors, not the envelope above:

{
  "error": "invalid_grant",
  "error_description": "invalid_username_or_password"
}

This is returned when username or password doesn't match a valid developer account. See How to Get API Access.

Handling errors

Status	Retry?	What to do
`400`	No	Fix the request. For `DataValidationError`, map each `validationErrors` key to the matching input field. For `WEP_BadRequest`, read `message` to see which values are missing.
`401`	After re-authenticating	Request a new access token, then repeat the call once.
`403`	No	Check the user's role and company or employee access. If the message mentions an IP address or a password change, re-authenticate from the current network.
`404`	No	Check that the IDs in the route belong to a company or employee the user can see.
`500`	Yes, with backoff	Retry idempotent requests (`GET`, `PUT`, `DELETE`) up to 3 times with exponential backoff. Don't automatically retry `POST`.

Error message reference

Messages are shown without the timestamp prefix.

HTTP status	`errorCode`	Message	Endpoint	Cause	Fix
400	`null`	`Routing Number is invalid.`	Update Company Bank Account	`routingNumber` is missing from the request body.	Always include `routingNumber`.
400	`null`	`Class code does not exist.`	Create Workers' Compensation Rate	A `code` in `rates[]` doesn't match a code returned by the class code lookup.	Use only codes from the class code lookup step.
400	`null`	`New versions of Workers' Compensation Rate must have a EffectiveFrom date greater than the last existing EffectiveFrom date.`	Create Workers' Compensation Rate	`effectiveFrom` is not later than the most recent existing `effectiveFrom` for that `state`.	Send an `effectiveFrom` later than the latest existing one.
400	`WEP_BadRequest`	`<Caption>: Value_Required`	Update Employee Tax Setup	A required tax parameter has no value. One line is returned for each missing parameter.	Call Get Employee Tax Setup and send a value for every required parameter.
400	`EmployeeHasAnyTimeOffPolicy`	`Active Policy for this Employee Already Exists`	Employee Time Off Policy Setup	The employee already has an active time off policy.	Deactivate the existing enrollment first, or leave the employee on the current policy.

Reporting a problem

When you contact Worklio support, include the HTTP method, the full URL, the response status, the full message (its timestamp helps locate server logs), and the time of the request in UTC.