Status Response Codes

The following status codes can be returned in HTTP responses.

HTTP Code HTTP Description Notes
2xx OK Not an error; returned on success. This should also be used for business logic failures (e.g. booking_failure in CreateBookingResponse is populated)
400 Bad Request Bad Request/Invalid Arguments (merchant, service, slot not found, trying to book an invalid slot, cancelling a booking that never existed).
401 Unauthorized Unauthenticated (invalid credentials, retry login). The request does not have valid authentication credentials for the operation.
403 Forbidden Permission denied/forbidden (caller is known and rejected). This response must not be used for rejections caused by exhausting some resource (use Too Many Requests instead for those errors). Forbidden must not be used if the caller can not be identified (use Unauthorized instead for those errors).
404 Not Found Not found (Resource not found, invalid url, including invalid RPCs)
409 Conflict The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort.
429 Too Many Requests Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
499 Client Closed Request The operation was cancelled, typically by the caller.
500 Internal Server Error Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.
501 Not Implemented The operation is not implemented or is not supported/enabled in this service.
503 Service Unavailable The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff.
504 Gateway Timeout The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.

Sometimes multiple error codes may apply. Services should return the most specific error code that applies.