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

35

No contractorID in the body/query of the request

Corresponds with HTTP 400

36

Object(s) does not have a bank account

Corresponds with HTTP 400

37

Cannot onboard employee: missing property

Corresponds with HTTP 400

38

Employee is already onboarded

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

42

No contractorID or employeeID in the body/query of request

Corresponds with HTTP 400

43

Employee Check with this check ID does not exist

Corresponds with HTTP 400

44

Date is not a valid date

Corresponds with HTTP 400

45

Date must not be in the past

Corresponds with HTTP 400

46

Contractor Payment with this payment ID does not exist

Contractor Payment with this payment ID does not exist

47

Validation Error

Corresponds with HTTP 403

48

The address provided is not a valid, mail deliverable address

Corresponds with HTTP 400

49

Company must be live

Corresponds with HTTP 403

50

Must provide a valid companyID

Corresponds with HTTP 400

51

No company with this companyID exists

Corresponds with HTTP 404

52

No document with this document ID exists

Corresponds with HTTP 404

53

No document of this type within the given scope exists

Corresponds with HTTP 404

54

No document with this jurisdiction and company ID have been submitted.

Corresponds with HTTP 404

55

Shifts with negative wages not currently supported

Corresponds with HTTP 400

56

Routing number is invalid

Corresponds with HTTP 400

57

Employee or contractor has not finished onboarding

Corresponds with HTTP 400

58

Work Location(s) not found

Corresponds with HTTP 400

59

Failed to update/upsert Work Location

Corresponds with HTTP 400

60

Failed to create Work Location

Corresponds with HTTP 400

61

Another employee in this company already has the same SSN

Corresponds with HTTP 400

62

Create employees payload contains duplicate SSNs

Corresponds with HTTP 400

63

SSN must be an optional property or of type string

Corresponds with HTTP 400

64

Request is not of the expected shape

Corresponds with HTTP 400

65

Maximum number allowed checks exceeded

Corresponds with HTTP 400

66

Only pending checks can be previewed. Received non pending check(s)

Corresponds with HTTP 400

67

No workLocationID in the body of request

Corresponds with HTTP 400

68

Bank Account with this employeeID or contractorID does not exist

Corresponds with HTTP 400

69

Another employee in this company already has the same external ID

Corresponds with HTTP 400

70

Another contractor in this company already has the same external ID

Corresponds with HTTP 400

71

No W-4 exists for this jurisdiction

Corresponds with HTTP 400

72

Employee or Contractor ID is not formatted correctly

Corresponds with HTTP 400

73

Contractor with this contractorID does not exist

Corresponds with HTTP 400

74

Invalid check date

Corresponds with HTTP 400