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.