Best Practices for Error Handling

Some of the key best practices followed for error handling are:

Rate Limiting: To prevent overconsumption of resources, the API imposes Rate Limits. This helps maintain the stability and performance of the system.
Optimized Code: Developers are advised to optimize their code to minimize the chances of errors and to make the best use of the available resources.
Graceful Error Handling: In case of an error response, your team should understand common causes of errors implement a retry mechanism, when it makes sense, to ensure a smooth user experience and to avoid any disruptions in the integrated systems.

Troubleshooting Chart

This chart outlines the error codes, their descriptions, and possible solutions to resolve the issues. By referring to this chart, your development and support teams can identify and address the problem at hand.

API Common Errors

Error	Error Type	Description / Recommended Action
301	Moved Permanently	The API resource has been replaced and is no loner accessible. The error message from this error code will include the new resource that should be used in place of this retired resource.
400	Bad Request	The request failed due to incorrect syntax or a missing parameter. Evaluate the response body and verify the request was sent in the correct format with all required parameters.
401	Unauthorized	The authorization token was either missing or invalid for the environment being called. Verify that the clientID and secret that were used to obtain the authorization token are correct and appropriate for the environment being called.
403	Forbidden	The client doesn't have permissions to perform the request. If this is an error received during testing, verify with Paylocity support that your credentials are authorized to access to this resource.
404	Resource not found	The requested resource does not exist. Check to see if the requested record exists in the Paylocity system.
409	Gone	The requested resource has been retired and is no longer available.
415	Unsupported Media Type	The payload format is unsupported. Verify that the media type being sent is supported by the resource.
429	Too Many Requests	Making too many calls within a given period of time. Review Rate Limits for further details on call volume ceilings. Coding should be put into place to prevent receiving a 429 response for too many requests. Logic should also be implemented to handle a 429 response if it happens, to retry the call to the API later.
500	Server Error	Unsuccessful retrieval of a resource due to a system error. Retry, if fails, contact support.
503	Service Unavailable	Gateway services is unavailable. Wait and retry later.

Error Model

[
  { 
    "code" : "field_required",
    "message" : "The field is required",
    "fields" : "firstName"
  }
]

Customer Support

If further assistance is required, API customers and partners can reach out to our dedicated support team at [email protected].. Web Services is readily available to assist your integration support teams in resolving issues they face while using our APIs.