Skip to main content
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 codeDescription
200   OKEverything worked as expected and the request succeeded.
400   Bad RequestThe request could not be understood by the server, usually due to malformed syntax such as a missing required parameter.
401   UnauthorizedThe client has not provided a valid Authentication HTTP header.
403   ForbiddenThe client has provided a valid Authentication header, but it does not have permission to access this resource.
404   Not FoundThe 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.