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
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 or access has been locked due to exceeding rate limit thresholds. If this is a request that has been successful with previously requests. Wait and retry. 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.
415	Unsupported Media Type	The payload format is unsupported. Verify that the media type being sent is supported by the resource.
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.