HTTP Status Codes

HTTP status codes are 3-digit numeric codes (100-599) returned in HTTP responses to indicate the result of a request. They are organized into 5 categories: 1xx informational, 2xx success, 3xx redirection, 4xx client error, 5xx server error. gRPC status codes are a separate set of 17 codes (0-16) used in gRPC (Google Remote Procedure Call) communication. Each gRPC code has a corresponding HTTP equivalent, but the mapping is not always one-to-one. For example, gRPC FAILED_PRECONDITION, INVALID_ARGUMENT, and OUT_OF_RANGE all map to HTTP 400.

The official gRPC-to-HTTP mapping is: OK→200, CANCELLED→499, UNKNOWN→500, INVALID_ARGUMENT→400, DEADLINE_EXCEEDED→504, NOT_FOUND→404, ALREADY_EXISTS→409, PERMISSION_DENIED→403, RESOURCE_EXHAUSTED→429, FAILED_PRECONDITION→400, ABORTED→409, OUT_OF_RANGE→400, UNIMPLEMENTED→501, INTERNAL→500, UNAVAILABLE→503, DATA_LOSS→500, UNAUTHENTICATED→401. This mapping is used by gRPC-Gateway and similar HTTP/gRPC bridging tools.

All three map to HTTP 400 but have different semantics. INVALID_ARGUMENT (3) means the argument is invalid regardless of system state (e.g., malformed email). FAILED_PRECONDITION (9) means the system is not in the required state (e.g., deleting a non-empty directory). OUT_OF_RANGE (11) means the value is outside the valid range (e.g., page number beyond total pages). Use INVALID_ARGUMENT for validation errors, FAILED_PRECONDITION for state-dependent rejections, and OUT_OF_RANGE for range violations.

UNAUTHENTICATED (16, maps to HTTP 401) means the request lacks valid authentication credentials — the caller has not identified themselves. PERMISSION_DENIED (7, maps to HTTP 403) means the caller is authenticated but does not have sufficient permission for the operation. In short: UNAUTHENTICATED is "who are you?" and PERMISSION_DENIED is "I know who you are, but you cannot do this."

Both map to HTTP 409 (Conflict) but have different use cases. ALREADY_EXISTS (6) should be used when attempting to create a resource that already exists (e.g., duplicate username registration). ABORTED (10) should be used for concurrency conflicts where the operation was aborted due to a transaction conflict or race condition, and the client may retry the entire read-modify-write sequence.

UNAVAILABLE (14, maps to HTTP 503) indicates the service is temporarily unavailable. Unlike INTERNAL (13) which indicates a bug or invariant violation, UNAVAILABLE signals a transient condition that may be resolved by retrying with exponential backoff. Use it for maintenance windows, temporary overload, or network connectivity issues. Clients should treat this as a signal to retry.

Click the HTTP or gRPC tab to switch between the two status code systems. Type any text in the search box to filter by code number, name, or description. For HTTP codes, use the category buttons (All, 1xx, 2xx, 3xx, 4xx, 5xx) to filter by range. For gRPC codes, click any code card to expand its details showing when to use the code and example scenarios. The search works across both tabs independently.

502 Bad Gateway occurs when a server acting as a gateway or proxy receives an invalid response from an upstream server. 504 Gateway Timeout occurs when the gateway did not receive a timely response from the upstream server. Common causes include upstream server crashes, network issues between proxy and origin server, or backend application timeouts. In gRPC, DEADLINE_EXCEEDED (4) is the equivalent of 504, while INTERNAL (13) or UNAVAILABLE (14) may correspond to 502 scenarios.