Errors

Permutive uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the information provided in the request (e.g. a required parameter was missing), and codes in the 5xx range indicate an error with Permutive’s API.

HTTP status codes

You may encounter the following response codes. Any unsuccessful response will contain more information to help you identify the cause of the problem.

Response code	Description
`200` OK	Everything worked as expected and the request succeeded.
`400` Bad Request	The request could not be understood by the server, usually due to malformed syntax such as a missing required parameter.
`401` Unauthorized	The client has not provided a valid Authentication HTTP header.
`403` Forbidden	The client has provided a valid Authentication header, but it does not have permission to access this resource.
`404` Not Found	The requested resource cannot be found or does not exist.
`500`, `502`, `503`, `504` Internal Server Error	The server encountered an error while processing your request and failed. Something went wrong on Permutive’s end.

Subcodes

If there has been an error (non-200 response), the body of the response will be a JSON object that describes the error in more detail. To help you better understand what went wrong and reference the problem, the API defines an error subcode and human-readable messages for every type of error that can occur. The docs field provides a resource where you can find out more information about this error. If you wish to contact our support team about any API errors, you can reference the request_id of your request. All error responses from the API follow a common format. Here’s an example response to a request with an invalid API key:

HTTP/1.1 401 Unauthorized
{
  "request_id": "e2cef6f6-296d-4044-b362-73fb2bce4a72",
  "error": {
    "status": "Unauthorized",
    "code": 2000,
    "message": "The API key provided is invalid.",
    "cause": "This key does not exist.",
    "docs": "https://developer.permutive.com/docs/errors/401/2000"
  }
}

Every field is guaranteed, other than cause which is optional.

Understanding errorsIf you’re unclear on what an error means, or want more help please get in touch using the chat widget or by emailing Support.

API Documentation

Events API

Identity API

Contextual API

Custom Cohort Segmentation API

Cohorts API

Taxonomy API

HTTP status codes

Subcodes

​HTTP status codes

​Subcodes

HTTP status codes

Subcodes