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"
    }
  ]
}