Kustomer uses conventional HTTP response status codes to indicate the success or failure of an API request. In general:

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate a client-specific error that failed given the information provided (for example, a required parameter was omitted, token is not authorized for a particular action, or an object creation failed due to conflict).
  • Codes in the 5xx range indicate an error with Kustomer's servers (these should be rare).
HTTP Status CodeDescription
200 OKEverything worked as expected
201 CreatedA new object was created as a result of the request
204 No BodyWe have acknowledged the request but do not return a body in the response. This can signal further asynchronous processing or a case where returning a body is superfluous (such as in response to a DELETE request).
400 Bad parameterThis usually is related to invalid data in the URL or request body.
401 UnauthorizedThis can be the result of an missing role, invalid auth token, or billing feature
404 Not FoundThe resource cannot be found or does not exist within scope.
409 ConflictTypically related to optimistic locking or other conflict that exists based on the request attempted.
413 Request Entity Too LargeReturned when the request body exceeds the allowed size (100kb for most endpoints, 400kb for hook transactions)
429 Rate Limit ExceededSee Rate limiting for more info.
500, 501 - Server ErrorsSomething went wrong on Kustomer's end

Our APIs return errors for many reasons, such as a failed creation, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.


In the following example, the request failed because the user doesn't have the proper permission set role to access that endpoint.