Troubleshooting API Responses

Welcome to your lifeline. The place you come after you're trying to create a resource via POST & it's coming back with a 404 error. Take a moment and relax, you've come to the right place. Or maybe you're just really into codes & understanding what they mean. Either way, welcome to the Troubleshooting API Responses page. Oh & if none of this works, try turning on & off again.

Common Error Codes

400

HTTP Status Code: 400
Definition:The server could not understand the request due to invalid syntax (user input error).

Solution: Review the request body, ensure there are no incorrect characters eg. } , ] etc.

401

HTTP Status Code: 401
Definition: Request included incorrect authentication headers.

Example Response

{
 "errors": [
 {
 "code": "authentication_failed",
 "detail": "Invalid X-USER-USERNAME or X-USER-TOKEN",
 "status": "401"
 }
 ]
}

Solution: Check the authentication headers ie. USER-TOKEN may have expired & needs to be re-generated by the Company Administrator.

403

HTTP Status Code: 403
Definition: Unable to access the resource. User is not authorised to perform the requested action.

Example Response

{
 "errors": [
 {
 "detail": "You are not authorised to access and/or modify this Resource",
 "code": "access_denied",
 "status": "403"
 }
 ]
}

Solution: Check the request. This may be due to a relationship or the work_employee_id not being defined, so the targeted record cannot be accessed unless it is defined.

404

HTTP Status Code: 404 - Not Found
Definition: The resource could not be found. The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.

Example Response

{
 "errors": [
 {
 "detail": "Unable to find the resource you requested",
 "code": "record_not_found",
 "status": "404"
 }
 ]
}

Solution: Review the request - the record may have been deleted.

409

HTTP Status Code: 409 - Conflict
Definition: The request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request.

Solution: Usually when trying to complete PATCH - double-check your work (JSON body, endpoint) & try again.

410

HTTP Status Code: 410 - Gone
Definition: The server encountered an unexpected condition that prevented it from fulfilling the request and/or the server did not know how to handle the unexpected situation.

Example Response

{
 "errors": [
 {
 "detail": "The requested resource has been archived",
 "code": "resource_archived",
 "status": "410"
 }
 ]
}

Solution: Either restore the resource, or create a new resource & then try again.

422

HTTP Status Code: 422 - Unprocessable Entity
Definition: The request was well-formed but was unable to be followed due to semantic errors. Similar to Error Code 415 & 400, but falls in-between those 2 errors.

Example Response

{
 "errors": [
 {
 "source": {
 "pointer": "/data/attributes/code"
 },
 "detail": "has already been taken by an inactive department"
 }
 ]
}

Solution: Review the URL, review the JSON body request and ensure all endpoint & body data is correct.

429

HTTP Status Code: 429 - API rate limit exceeded.
Definition: The user has sent too many requests in a given amount of time.

Solution: Wait, make a sandwich or something & then try again.

500

HTTP Status Code: 500 - Internal Server Error
Definition: The server encountered an unexpected condition that prevented it from fulfilling the request and/or the server did not know how to handle the unexpected situation.

Solution: Review the URL, review the JSON body request and ensure all endpoint & body data is correct.

For more API response codes & what they mean, visit HTTP Status Codes.

API Specific Error Messages

Error message	Description	How to fix it?
`authentication_failed`	Invalid X-USER-USERNAME or X-USER-TOKEN	Set (or reset) http headers: X-USER-USERNAME {company_admin_email} X-USER-TOKEN {your-api-key}
`access_denied`	You are not authorised to access and/or modify this Resource	Make sure the resources are your company’s resources
`unknown_format`	Accept and Content-Type headers must be "application/vnd.api+json"	Set Accept and Content-Type headers to be "application/vnd.api+json"
`unknown_error`	An Unknown Error has occurred with your request	Unhandled error on the server, report to support
`record_not_found`	Unable to find the resource you requested	Change the URL and use the right ID
`resource_archived`	The requested resource has been archived	Call the restore API to restore the resource
`invalid_endpoint`	Invalid endpoint requested	Change the wrong URL
`invalid_parameter`	Unable to use the requested parameter value	Change your URL parameters
`parameter_missing`	Your request is missing a required parameter	Add the parameter according to the documentation
`resource_exists`	Resource already exists	Change the resource primary key, like: ID or CODE
`invalid_document_type`	Request json_api data type does not match endpoint	Change the data type to match the endpoint
`invalid_document`	Request json_api document is invalid	The JSON payload should start like: { "data" : { ... }}
`invalid_document_identifier`	Request json_api data id is invalid	Change the data ID in JSON payload
`missing_relationship`	Unable to find the requested relationship	Confirm the requested relationship existed
`unauthorized_resource`	Unable to access the requested resource	Confirm the resources are your company’s resources
`unauthorized_relationship`	Request json_api relationship can not be updated by the current endpoint	Change the way to update the relationship
`invalid_attribute`	Request json_api attribute data is invalid	Check the JSON payload attributes part

Common Error Codes

Example Response

Example Response

Example Response

Example Response

Example Response

API Specific Error Messages

Comments

Related articles