HTTP Status Code Guide

2xx: Success

These codes indicate that the client's request was successfully received, understood, and accepted.

Code	Status	Description	Dev Action
200	`OK`	Standard response for successful requests.	Handle the response body data.
201	`Created`	The request has been fulfilled and a new resource has been created.	Check the `Location` header or body for the new ID.
202	`Accepted`	Request accepted for processing, but processing is not complete.	Poll for status updates if applicable.
204	`No Content`	Request succeeded, but there is no content to send back.	Don't expect a response body (often used for DELETE).

These codes indicate that further action needs to be taken by the user agent in order to fulfill the request.

Code	Status	Description	Dev Action
302	`Found`	The requested resource resides temporarily under a different URL. Used heavily for 3D Secure flows, OAuth callbacks, and hosted checkout navigation.	Browser: Follows automatically. API/Server: Read the Location header and redirect the user there.

These codes indicate that the client seems to have erred (e.g., malformed syntax, invalid parameters).

Code	Status	Description	Dev Action
400	`Bad Request`	The server cannot process the request due to a client error (e.g., invalid JSON).	Validate your payload/parameters against the schema.
401	`Unauthorized`	Authentication is required and has failed or has not been provided.	Check your Bearer token or API key.
403	`Forbidden`	The server understood the request but refuses to authorize it.	Check user permissions/scopes.
404	`Not Found`	The requested resource could not be found.	Verify the URL path and ID.
409	`Conflict`	Request conflicts with the current state of the server.	Often happens on duplicate entries (e.g., double sign-up).
418	`I'm a Teapot`	The server refuses the attempt to brew coffee with a teapot.	Used for custom exceptions.
422	`Unprocessable Entity`	Semantic errors in the request (e.g., password too short).	Check validation error messages in the body.
429	`Too Many Requests`	The user has sent too many requests in a given amount of time.	Implement exponential backoff.

These codes indicate that the server failed to fulfill an apparently valid request.

Code	Status	Description	Dev Action
500	`Internal Server Error`	A generic error message when an unexpected condition was encountered.	Check server logs/Sentry for stack traces.
502	`Bad Gateway`	The server received an invalid response from the upstream server.	Check if the DB or internal microservices are down.
503	`Service Unavailable`	The server is currently unable to handle the request (overloaded/maintenance).	Retry the request later.
504	`Gateway Timeout`	The upstream server failed to send a request in time.	Optimize query performance or check network latency.