Error codes

All Zeal responses follow HTTP Status Codes.

HTTP Status

Meaning

200 - OK

Everything worked as expected

400 - Bad Request

The request was unacceptable, often due to a missing or incorrect required parameter

401 - Unauthorized

No valid API Key provided

402 - Request Failed

The parameters were valid but the request failed

403 - Forbidden

The API key doesn't have permissions to perform the request

404 - Not Found

The requested resource doesn't exist

409 - Conflict

The request conflicts with another request

429 - Too Many Requests

Too many requests hit the API too quickly. We recommend an exponential backoff of your requests

500,502,503,504 - Server Errors

Something went wrong on Zeal's end

Zeal API error messages are returned in JSON format.

{
   "success": false,
   "errors": [
      {"message":"Employee does not exist", "code":30}
   ]
}

Error Code

Message

Description

0

This account does not have access to live payroll. You may only use Test Keys/Test Mode for now.

Corresponds with HTTP 403.

The account does not have access to live payroll yet. Please contact [email protected] to gain access.

1

No Authorization Header

Corresponds with HTTP 400.

No authorization header or Bearer Token was found in request

2

No companyID in the request query

Corresponds with HTTP 400.

No companyID was found in query of request when expected.

3

No companyID in the request body

Corresponds with HTTP 400.

No companyID was found in the body of the request when expected.

4

No user with this companyID exists.

Corresponds with HTTP 400.

No user with the given companyID exists.

5

Error with key.

Corresponds with HTTP 401.

Given API key does not exist for user with given companyID

6

No partnerID in body or query of request

Corresponds with HTTP 400.

No partnerID was found in the body or query of request when expected

7

No Zeal Partner with this partnerID exists

Corresponds with HTTP 400.

No Zeal Partner with the given partner ID exists.

8

Error with Key

Corresponds with HTTP 401.

Given API key does not exist for Zeal partner with given partnerID

9

Invalid format for time given in query

Corresponds with HTTP 400.

The format of the time parameter for the request does not adhere to ISO-8601 format.

10

Reporting Period with this ID does not exist

Corresponds with HTTP 400.

No Reporting Period with this ID exists.

11

No 'shifts' array found in the body of the request

Corresponds with HTTP 400.

12

Worker(s) with given employeeID(s) in the body of the request does not exist

Corresponds with HTTP 400.

13

Object(s) is missing required fields or has improperly formatted data

Corresponds with HTTP 400. Consult API reference for proper formatting.

14

Shift(s) have been assigned wages below minimum wage

Corresponds with HTTP 400.

*Please pay employees over minimum wage.

15

Shift(s) with given shiftID(s) is not found for this user

Corresponds with HTTP 404.

This could have occurred because of an improperly formatted shiftID.

16

No employeeCheckID found in the query of request

Corresponds with HTTP 400

17

Object with this ID does not exist

Corresponds with HTTP 400

18

No end date found in query of request

Corresponds with HTTP 400

19

No start date found in query of request

Corresponds with HTTP 400

20

Dates provided in query of request are invalid/inappropriately formatted

Corresponds with HTTP 400. Please format dates as YYYY-MM-DD

21

End Date occurs before Start Date

Corresponds with HTTP 400.

22

No 'employees' array found in the body of request

Corresponds with HTTP 400

23

Employee with this employeeID does not exist

Corresponds with HTTP 400.

24

Zeal Partner does not have access to this company's information

Corresponds with HTTP 400

25

This is only a Live Mode feature. Test Key does not have permission to perform this request.

Corresponds with HTTP 403.

26

No shiftID in the query of request

Corresponds with HTTP 400

27

No 'new_employees' array found in the body of the request

Corresponds with HTTP 400

28

Employee object(s) are missing the required fields.

Corresponds with HTTP 400

29

Worker(s) with given email(s) already exist. Please try again

Corresponds with HTTP 404

30

Employee is already onboarded/on leave/terminated

Corresponds with HTTP 404

31

No Pending Employee Check exists within the given employeeCheckID

Corresponds with HTTP 404

32

Employee Check for this employee and check date already exists. Error object will include an employeeID and check date

Corresponds with HTTP 400

33

This employee is working in a state for which a State Payroll Tax Number has not been submitted. This error only applies in Live Mode

Corresponds with HTTP 400.

34

The address provided is not suitable for taxation. Address fields where wholly invalid or resolved to a taxable location with is_suitable_for_taxation equal to false. Use the Resolve Taxable Location endpoint for more details.

Corresponds with HTTP 400.

39

Internal Server Error

Corresponds with 500. Message will relay actual server error.

40

CompanyID mismatch in body and query of request

Corresponds with HTTP 400.

41

Key is not authorized to perform this request

Corresponds with HTTP 403