-
Notifications
You must be signed in to change notification settings - Fork 5
API Error Handling Response Guide
The following document outlines which errors that the API should return in different error situations.
Do return 401 when a request to a private endpoint includes no JWT or an invalid JWT.
Why? 401 communicates that the client must authenticate to access the endpoint.
Why? It is the canonical status for requests that lack proper authentication credentials.
Do return 400 for client mistakes like malformed JSON, missing required fields, or data that fails “fast-fail” validation.
Do provide a helpful message describing the error, e.g. which field is invalid or missing.
Why? 400 indicates the client’s request is invalid and cannot be processed.
Why? It avoids confusion with other error types (like 404 for missing resources).
Do return 403 if a user is authenticated but lacks the roles/permissions to access the endpoint entirely. Example: An endpoint can only be called by Administrators, but the user is a standard user.
Why? 403 clearly indicates “I know who you are, but you do not have the privileges to access this endpoint.”
Why? This differs from 401 (not authenticated) and 404 (resource not found or not visible).
Do return 404 if a resource does not exist in your system.
Do return 404 if the resource exists but the user cannot access it (you want to conceal its existence).
Why? 404 is unambiguous for resources that do not exist, or for resources that the user is not allowed to see (thereby hiding its existence).
Why? This approach thwarts attempts at enumerating resource IDs by external parties who should not even know the resource exists.
Do return 500 if an unhandled exception occurs within your application code.
Do return 500 if an external API request fails in a way that prevents your endpoint from functioning.
Why? 500 is the canonical way to say “Something went wrong on our end that we didn’t anticipate.”
Why? From the user’s perspective, your service failed to fulfill the request.
Consider using 502 (Bad Gateway) or 503 (Service Unavailable) for external service outages if debugging upstream issues becomes an issue.