HTTP status codes

Handling errors properly is crucial in API design. APIs should use standard HTTP status codes and provide clear error messages.

Overview of HTTP status codes

Status Code	Status	Description	Set by Gateway	Set by Backend
2xx Success
200 OK	Success	The API call was successful.	No	Yes
201 Created	Success	A new entity was successfully created.	No	Yes
202 Accepted	Success	The request was accepted but has not yet been processed.	No	Yes
204 No Content	Success	The request was successful, but no content is returned.	No	Yes
4xx Client Error
400 Bad Request	Error	The request could not be processed due to a client error.	Yes	Yes
401 Unauthorised	Error	Invalid API key or authentication token.	Yes	Yes
403 Forbidden	Error	The client does not have permission to access the resource.	Yes	Yes
404 Not Found	Error	The requested resource does not exist.	Yes	Yes
405 Method Not Allowed	Error	The HTTP method used is not supported for this endpoint.	Yes	Yes
415 Unsupported Media Type	Error	The Content-Type header is incorrect.	Yes	Yes
429 Too Many Requests	Error	The request quota was exceeded (rate limiting).	Yes	No
5xx Server Error
500 Internal Server Error	Error	An unexpected backend failure occurred.	No	Yes
502 Bad Gateway	Error	The backend received an invalid response.	Yes	Yes
503 Service Unavailable	Error	The backend is temporarily unavailable. A retry may be required.	No	Yes
504 Gateway Timeout	Error	The backend did not respond within the required timeframe.	Yes	Yes

Error messages

APIs should return clear and descriptive error messages in JSON format when an error occurs.

Convention: Return error messages in JSON format.

Example (401 Unauthorized)

{
    "errors": [
        {
            "errorCode": "xyz",
            "errorMessage": "Sorry, this is not working",
            "correlationId": "12sdfkjsdkjjsdf",
            "link": "https://developer.wpp.com/api/ambee/errorcodes/xyz"
        }
    ]
}

Do not return stack traces, as they may contain sensitive information.

Example scenarios

GET request identifying a set of resources

GET /v1/senders?first_name=Peter&last_name=Brown

Response (200 OK)

{
    "data": [
        {
            "id": "1",
            "firstName": "Peter",
            "lastName": "Brown",
            "city": "London"
        },
        {
            "id": "2",
            "firstName": "Peter",
            "lastName": "Brown",
            "city": "New York"
        }
    ]
}

Response (Empty List, 200 OK)

{
    "data": []
}

Response (400 Bad Request)

{
    "errors": [
        {
            "status_code": 400,
            "detail": "'id' value is not a number"
        }
    ]
}