Error Codes

All of Zeal’s 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 permission 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 403The account does not have access to live payroll yet. Please contact Zeal support to gain access.
1	No Authorization Header	Corresponds with HTTP 400No authorization header or Bearer Token was found in the request
2	No companyID in the request query	Corresponds with HTTP 400No companyID was found in the query of request when expected.
3	No companyID in the request body	Corresponds with HTTP 400No companyID was found in the body of the request when expected.
4	No user with this companyID exists	Corresponds with HTTP 400No user with the given companyID exists.
6	No partnerID in the body or query of request	Corresponds with HTTP 400No partnerID was found in the body or query of the request when expected
7	No Zeal Partner with this partnerID exists	Corresponds with HTTP 400No Zeal Partner with the given partner ID exists.
8	Error with Key	Corresponds with HTTP 401Given API key does not exist for Zeal partner with given partnerID
9	Invalid format for the time given in the query	Corresponds with HTTP 400The format of the time parameter for the request does not adhere to the ISO-8601 format.
10	Reporting Period with this ID does not exist	Corresponds with HTTP 400No 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 have improperly formatted data	Corresponds with HTTP 400. Consult API reference for proper formatting.
14	Shift(s) with given shiftID(s) is not found for this user	Corresponds with HTTP 404This could have occurred because of an improperly formatted shiftID.
16	No employeeCheckID found in the query of the request	Corresponds with HTTP 400
17	Object with this ID does not exist	Corresponds with HTTP 400
18	No end date found in the query of the request	Corresponds with HTTP 400
19	No start date found in the query of the request	Corresponds with HTTP 400
20	Dates provided in the 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 the 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 the 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 has 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 of 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 the 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
75	Must be valid SSN format - eg. XXXYYZZZZ	Corresponds with HTTP 400
76	Another contractor in this company already has the same SSN	Corresponds with HTTP 409
77	Start date cannot be after end date	Corresponds with HTTP 400
78	Email already exists	Corresponds with HTTP 409
79	Migration failed	Corresponds with HTTP 400
80	Please provide a file to upload	Corresponds with HTTP 400
81	Contractor Payment for this contractor and pay date already exists. Error object will include a contractorID and pay_date	Corresponds with HTTP 400
82	CompanyID was not found	Corresponds with HTTP 400
83	Failed to retrieve Partner Information by ID	Corresponds with HTTP 400
84	Email or password is incorrect	Corresponds with HTTP 401
85	Partner not found	Corresponds with HTTP 400
86	Either document ID or type, jurisdiction, and scope are required	Corresponds with HTTP 400
87	Employee has missing or invalid residency	Corresponds with HTTP 422
88	Contractor is already onboarded	Corresponds with HTTP 400
89	The given date is on a weekend/bank holiday or the current time is after 2 PM two days before the given date. Please correct the date and resubmit	Corresponds with HTTP 400
90	Only able to regenerate requirement for state-scoped requirements	Corresponds with HTTP 400
91	Invalid tax parameter jurisdiction	Corresponds with HTTP 400
92	Invalid tax requirement ID	Corresponds with HTTP 400
93	Invalid tax parameter value	Corresponds with HTTP 400
94	Employee’s default wage has not been set so please provide an appropriate wage in the shifts object(s)	Corresponds with HTTP 400
95	The requested feature is disabled	Corresponds with HTTP 403
96	Value must be positive	Corresponds with HTTP 400
97	Email must be valid	Corresponds with HTTP 400
98	This account does not have access to this endpoint	Corresponds with HTTP 403
99	This employee is not onboarded	Corresponds with HTTP 400
100	This employee is on leave/terminated	Corresponds with HTTP 400
101	Forbidden	Corresponds with HTTP 403
102	You must create between 1 and 100 checks	Corresponds with HTTP 400
103	Unauthorized	Corresponds with HTTP 401
104	Provided deduction template id(s) not found under companyID	Corresponds with HTTP 404
105	Parameter is expected to be of type objectid string	Corresponds with HTTP 400
106	Net pay negative - this check will fail	Corresponds with HTTP 422
107	Bad Form Data	Corresponds with HTTP 422
108	Provided check is invalid	Corresponds with HTTP 400
109	Accrual policy with this policy code not found	Corresponds with HTTP 404
110	Historical shift would be modified by overtime calculation	Corresponds with HTTP 422
111	Value for earning type must be less than 0	Corresponds with HTTP 400
112	Value must be negative	Corresponds with HTTP 400
113	Jurisdiction does not exist	Corresponds with HTTP 404
114	Company not setup for regular payroll	Corresponds with HTTP 400
115	Account not found	Corresponds with HTTP 404
116	Value must be a decimal	Corresponds with HTTP 400

Introduction

Webhooks

Zeal Components

Companies

Company Onboarding

Reserve Accounts

Customer Accounts (Early Access)

Taxable Locations

Work Locations

Employees

Employee Deduction Templates

Employee Onboarding

Bank Accounts

Custom Attributes

Paperwork API

Employee Checks

Contractors

Contractor Onboarding

Contractor Payment Deductions

Payment Items

Contractor Payments

Paycards

Instant Pay

Employer Checks

Preview

Embedded HR

Reports

Documents