HTTP response status codes

We use a limited number of status codes to make communication between back-end and front-end easier.

• 200 HTTP_OK
• 301 HTTP_MOVED_PERMANENTLY
• 302 HTTP_FOUND
• 307 HTTP_TEMPORARY_REDIRECT
• 308 HTTP_PERMANENTLY_REDIRECT
• 400 HTTP_BAD_REQUEST
• 403 HTTP_FORBIDDEN
• 404 HTTP_NOT_FOUND
• 405 HTTP_METHOD_NOT_ALLOWED
• 410 HTTP_GONE If resource is not available anymore (example: completed Transaction)
• 413 HTTP_REQUEST_ENTITY_TOO_LARGE Request body size is limited on nginx level: client_max_body_size 20M
• 422 HTTP_UNPROCESSABLE_ENTITY Validation error. ⚠️ Has a standardized JSON response structure, see 422
• 429 HTTP_TOO_MANY_REQUESTS Usually generated by ThrottleRequests middleware.
• 500 HTTP_INTERNAL_SERVER_ERROR Generic server error
• 503 HTTP_SERVICE_UNAVAILABLE Maintenance mode
• 504 HTTP_GATEWAY_TIMEOUT Gateway timeout

422

This is a special case to display validation errors, so we need a consistent way to structure data. We used Laravel’s convention. For JSON responses, it looks like:

{
    "message": "The given data was invalid.",
    "errors": {
        "email": ["The email must be a valid email address."],
        "name": ["The name must be at least 2 characters.", "The name may only contain letters."]
    }
}

Where "email" and "name" are input names that have not passed validation.

Materials

How many HTTP status codes should your API use?