Response Codes
The API uses standard HTTP status codes to indicate the success or failure of the API call. All requests return one of these standard HTTP response codes
Id | Meaning | Description |
---|---|---|
200 | OK | Everything worked as expected |
400 | Bad Request | The request was unacceptable and therefore couldn't be processed by API due to bad syntax (wrong data format or missing a required parameter). |
401 | Unauthorized | No valid API key provided |
403 | Forbidden | The API key doesn't have permissions to perform the request |
404 | Not Found | The requested resource doesn't exist |
422 | Unprocessable Entity | The request syntax was correct but an exception was caught in processing |
429 | Too Many Requests | Too many requests hit the API quickly |
50x | Server Errors | Something went wrong on Pax8 server (These should be rare) |
Errors
The body of each error response contains JSON in the following format:
{
"type": "Type of error",
"message": "Detailed message about the error/possible resolution",
"instance": "The path called",
"status": 404,
"details": [
{
"type": "Type of error (optional)",
"status": "HTTP Status (optional)",
"message": "Detailed message about the error/possible resolution (required)",
"instance": "The path called (optional)"
}
]
}
For example...
{
"type": "NOT_FOUND",
"message": "Company Not Found: 3d0617ac-57f6-40e3-951d-e91da47a326b",
"instance": "/public/v1/companies/3d0617ac-57f6-40e3-951d-e91da47a326b",
"status": 404,
"details": []
}
The server will respond with a 400 error in case of incorrect API usage, such as providing data with bad syntax or missing a parameter in the request. This pertains solely to improper API usage and should not be confused with an invalid business entity, etc. Such behavior applies to all APIs in general.
A Bad data format example:
Expected (correct) request data:
{
"companyId": "563beb00-9832-4e1a-9e30-d9e4cd4fc2585"
}
Unexpected request data due to bad data format; a wrong syntax JSON:
{
"companyId": 666666
}
Missing a parameter example:
Expected (correct) request data:
{
"partnerId": "563beb00-9832-4e1a-9e30-d9e4cd4fc2585",
"partnerName": "Test Partner",
"partnerCity": "Albuquerque"
}
Unexpected request data due to missing request parameter (partnerId is missing); a wrong syntax JSON:
{
"partnerName": "Test Partner",
"partnerCity": "Albuquerque"
}
Both examples of bad syntax will lead to 400 (Bad Request) error response from API like this:
400 API Error - Bad Request - Response example JSON:
{
"type": "BAD_REQUEST",
"message": "Api failed to process the request",
"instance": "/public/.../",
"status": 400,
"details": []
}
For Vendor Endpoints
When an error occurs the details map will contain a supportId
.
- This can be provided to Pax8 support when you need to troubleshoot error responses from the API.
{
"type": "invalid-request",
"status": 400,
"message": "field x must not be blank",
"instance": "/example",
"details": [
{
"supportId": "2f78b0321e2c945293108ded671cba51"
}
]
}
Updated 10 months ago