API Status Codes and Their Meanings

What do API status codes mean?

API status codes show whether an API request succeeded, needs more action, or failed. The first digit places an HTTP response in one of five groups: informational, successful, redirection, client error, or server error.

An HTTP status code is a standard three-digit value sent with a response, such as 200 or 404. An API-specific error code is a separate identifier defined by the API provider and usually appears in the response body. For example, an HTTP response may use a general client-error status while the body identifies the exact field or rule that caused the failure.

Read both kinds of code when they are available. The HTTP status describes the broad outcome, while the API-specific code, message, and field details may explain the particular problem.

What does a 1xx informational API status code mean?

A 1xx API status code means the server has received part of the request or is reporting progress before the final response. These responses are temporary and do not normally represent the completed result.

• 100 Continue: The client may continue sending a request body after the server accepts the initial request headers.
• 101 Switching Protocols: The server agrees to change protocols when the request and connection support that change.
• 102 Processing: The server is still working on the request. This code is uncommon and is not supported by every API.
• 103 Early Hints: The server supplies preliminary header information before the final response.

Many API libraries handle informational responses without exposing them to application code. If a client does receive a 1xx response, it should continue waiting for the final status unless the API documentation says otherwise.

Which 2xx API status codes mean success?

A 2xx API status code means the server received and successfully handled the request. The exact code shows what kind of successful result occurred.

• 200 OK: The request succeeded, commonly for retrieving or updating data. The response often includes a representation of the result.
• 201 Created: The request succeeded and created a new resource. Response headers or the body may identify the resource.
• 202 Accepted: The server accepted the request for processing, but processing may not be complete. The client may need to check a job or operation state as documented by the API.
• 204 No Content: The request succeeded, but the response intentionally has no body. The client should not treat an empty body as missing data or a parsing failure.
• 206 Partial Content: The server returned only the requested portion of a resource.

A successful status does not guarantee that an asynchronous task later finished successfully. With 202 Accepted, check the operation result through the method specified in the API documentation.

What should an API client do with a 3xx redirection status?

A 3xx response tells the client that another action or location may be needed. Redirect responses often include a Location header, which identifies the destination selected by the server.

• 301 Moved Permanently and 308 Permanent Redirect: The resource has a lasting new location. A client should update a stored endpoint only when the API documentation confirms that the change is expected.
• 302 Found, 303 See Other, and 307 Temporary Redirect: The destination is temporary. Method handling differs among these codes, so the client library must preserve or change the request method correctly.
• 304 Not Modified: A cached representation remains current. This is not a normal response containing fresh resource data.

Automatic redirects can hide useful details and may send credentials to an unintended host if configured carelessly. Inspect the Location header, confirm the destination, and check whether the request method, body, and authentication headers will be preserved.

What do common 4xx API status codes mean?

A 4xx API status code means the server found a problem with the request. The request may have invalid data, insufficient credentials, an unsupported method, or a resource state that prevents the operation.

• 400 Bad Request: The request is malformed or contains invalid input.
• 401 Unauthorized: Authentication is missing, expired, invalid, or otherwise not accepted.
• 403 Forbidden: The server recognizes the request but does not allow the authenticated identity to perform the operation.
• 404 Not Found: The requested route or resource was not found. Some APIs may also use this response to avoid revealing whether a protected resource exists.
• 405 Method Not Allowed: The route exists, but it does not accept the HTTP method used.
• 409 Conflict: The request conflicts with the resource's current state, such as a duplicate identifier or competing update.
• 415 Unsupported Media Type: The request body format does not match the declared or accepted content type.
• 422 Unprocessable Content: The syntax may be valid, but one or more values fail validation or business rules.
• 429 Too Many Requests: The client exceeded a request limit. Response headers may indicate when another attempt is allowed.

Do not repeatedly retry every 4xx response. Correct the request, credentials, permissions, or timing first. For 429 responses, follow documented rate-limit headers and reduce request frequency.

What do common 5xx API status codes mean?

A 5xx API status code means the server or an intermediary could not complete an apparently valid request. The failure may be temporary, but repeated requests can make an overloaded service worse.

• 500 Internal Server Error: The server encountered an unexpected failure.
• 501 Not Implemented: The server does not support the requested capability.
• 502 Bad Gateway: A gateway or proxy received an invalid response from an upstream server.
• 503 Service Unavailable: The service is temporarily unavailable, overloaded, or undergoing maintenance.
• 504 Gateway Timeout: A gateway did not receive an upstream response in time.

Retry only operations that are safe to repeat, using increasing delays and a retry limit. Check for a Retry-After header. Before retrying a request that creates or changes data, determine whether the first attempt may already have succeeded; an idempotency mechanism can help when the API documents one.

How do you troubleshoot an API status code?

1. Record the full response. Save the HTTP status, response body, timestamp, and request identifier. The body may contain an API-specific error code or invalid-field details.
2. Inspect response headers. Look for content type, authentication challenges, redirect locations, caching information, rate-limit fields, and retry guidance.
3. Compare the request with the specification. Check the method, endpoint, query parameters, required headers, body format, field types, and character encoding.
4. Verify authentication and authorization. Confirm that credentials are present, current, intended for the correct environment, and permitted to access the operation.
5. Check the API documentation. Match the status and any API-specific code to the documented meaning. Do not assume that every provider uses response bodies or less-common codes identically.
6. Check service-status information. For 5xx errors or widespread failures, determine whether the provider reports an incident or maintenance event.
7. Retry carefully. Retry only when the method is safe or protected against duplicate changes. Use increasing delays for temporary failures and rate limits.

If the cause remains unclear, create a minimal reproducible request with secrets removed. Include the request identifier and relevant response details when reporting the issue through the API provider's documented support process.