Response Codes

Status Codes

Paychex API will attempt to return an appropriate HTTP status code for every request. You should consult the documentation for each state transition on what you might expect for status codes. The following table provides a common understanding for status codes returned by Paychex APIs.

Currently available Status Codes:

CodeTextDescription
200OKThe state transition was successful.
401UnauthorizedThe authentication credentials are missing or incorrect. This often occurs when your bearer token is invalid or has expired. See OAuth 2.0 .
403ForbiddenThe request is understood but has been refused or access is not allowed. An accompanying error message will explain why. This often occurs when you try to access a resource or attempt to perform a state transition for which your API key has not been authorized to perform.
404Not FoundThe resource or state transitioned being requested is invalid.
429Too Many RequestsThis error is returned when a request cannot be served due to the application's rate limit having been exhausted for the resource. See Rate Limiting.
500Internal Server ErrorSomething is broken. Please contact Paychex support so we can investigate.

Future Status Codes:

CodeTextDescription
201CreatedThe state transition was successful and a new resource was created. The new resource can be referenced by using one of the links or entity returned in the response.
400Bad RequestThe request was invalid. An accompanying error message will explain further. This is typically used when authentication information or other required parameters are not provided.
406Not AcceptableThis is returned by state transitions that include a query parameter (search, pagination, filter) when a parameter or combination of parameters in the query are invalid. An accompanying error message will explain further.
410GoneThe resource or state representation being referenced no-longer exists. This may happen if you bookmark an identifier (id) and the resource associated with that identifier has been deleted or expired.
415Unsupported Media TypeThe media-type or one of the profiles specified is not valid or is no-longer supported.
503Service UnavailableThe Paychex servers are up but unable to service your request. This error is only returned in the sandbox environment.

 

Common Error Codes

Paychex API will return error information which can be used for handling and resolving problems. Errors which are specific for a resource will be available within its corresponding API reference area.

CodeHTTP StatusMessageResolution
API-17400Invalid value.Please enter a valid value.
API-6400The value for the {elementName} data element is too long.Change it so it is less than the maximum length.
API-8400The date range requires both start and end dates.null
API-102401The client could not be authenticated due to missing or invalid client credentials.Make sure that you are using the correct API key/Secret and that your application is enabled.
API-103401Bearer token is expired or invalid.Use the authorization service to generate a new token.
API-104401Missing or duplicate token.Send a valid token with your call.
API-100402Your request is too large.Please reduce the size.
API-2403Your application is not authorized access the {resource} resource: {resource ID}.Please have your company administrator give your application access to the resource.
API-7404The {resourceId} resource or state is invalid. You may have an incorrect resource ID.Send a valid resource in your request.
API-5422The {elementName} data element can't be modified.Submit the request without the data element or with the data element unedited.
API-5422The {elementName} data element can't be modified.Submit the request without the data element or with the data element unedited.
API-10423The client is locked because another user or process is updating it. Your changes cannot be saved while the client is locked.Please try again later.
API-1, API-3, API-105500Internal Server Error.Please contact Paychex API Developer Center Support.
API-4500The request isn't valid.null
API-9500Internal Server Error.Please contact Paychex API Developer Center Support.
{
   "content": [],
   "errors": [   {
      "code": "API-2",
      "description": "Your application is not authorized access the Worker resource: '00Z5V9BTIHRQF2CF7BTH'.",
      "resolution": "Please have your company administrator give your application access to the resource."
   }]
}