The Superchat API relies on conventional HTTP response codes to inform about the success or failure of an API request. Response codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Superchat's servers.

HTTP error codes in use

In detail, the API builds on the following HTTP codes to communicate errors:

HTTP Code	Error type	Description
400	Client error	The 400 error is thrown if there is a mismatch in types in the request body structure or if there are other illogical structures send to the API.
401	Unauthorized	The 401 errors is reported back if our servers could not authenticate your request.
404	Not found	The 404 error is sent in case you specified a resource that is not existent.
409	Resource conflict	The 409 error occurs if a resource cannot be updated due to internal logic contraints or a resource could not be created due to uniqueness constraints.
413	Content too large	The POST /files endpoint replies with a 413 error if the uploaded file size is larger than the allowed maximum.
500	Unexpected error	The API returns a 500 error in case of unexpected problems.

Error object

Each error is send with the same object that provides a title, detailed information and a link to docs that help to fix or mitigate the occurred issue.

{
  "errors": [
    {
      "title": "Contact not found",
      "detail": "No contact could be found for this resource identifier. Please make sure to use uuids and not hashed ids.",
      "url": "/contact/{contact_id}",
      "docs": "https://superchat.readme.io/frequent-contact-errors",
      "status_code": 404
    }
  ]
}

🚧
Migration to common error model
At this moment not all errors are reported in our common error model. Some errors still have a different payload structure which we seek to align in the coming weeks.