API status codes explained for testing

The four status groups API testers use most

The first digit places a response in a broad category. That category helps you decide whether to inspect the returned resource, follow a redirect, correct the request, or investigate the server.

2xx: successful requests

A 2xx response means the request was accepted, but the exact code still matters. Test whether the code matches the operation and whether the body follows the documented contract.

A common migration regression is returning 200 for every successful action. That can hide meaningful distinctions such as creation, asynchronous acceptance, and an intentionally empty response.

3xx: redirects and cached responses

Redirects are less common in JSON APIs than in websites, but they can appear after endpoint moves, authentication flows, or infrastructure changes. Check the Location header and whether the client is expected to follow the redirect automatically.

Pay special attention to 301 and 308 permanent redirects versus 302 and 307 temporary redirects. Some redirect types preserve the original method and body while others may be interpreted differently by clients. Test the actual client behavior rather than assuming every redirect is equivalent.

4xx: problems the client can address

A 4xx response says the server cannot fulfill the request as submitted. Good APIs distinguish between invalid input, missing authentication, insufficient permission, absent resources, state conflicts, and rate limits.

5xx: failures owned by the server

A 5xx code should represent a server or upstream failure, not ordinary invalid input. Test whether errors are logged internally, return a safe request identifier, and avoid exposing stack traces or confidential details.

Compare the error body as well as the code

Two APIs can return the same status while giving clients very different information. A stable error contract often includes a machine-readable code, a human-readable message, field-level details when appropriate, and a request or trace identifier.

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Enter a valid email address.",
    "field": "email",
    "requestId": "req_7f31"
  }
}

Do not assert only that an error occurred. Assert the expected HTTP status, error schema, stable machine code, and absence of private implementation details.

A practical status-code test matrix

• Valid request with an existing resource
• Valid request for a missing resource
• Missing, expired, and malformed credentials
• Authenticated user without permission
• Malformed JSON and missing required fields
• Duplicate creation or conflicting update
• Rate-limit exhaustion and retry behavior
• Dependency failure and timeout behavior

What to flag during a migration

Flag a change when the candidate returns a different status for the same logical outcome, turns a specific error into a generic one, changes the error-body schema, removes retry information, or exposes more internal detail. Document intentional changes so client teams can update safely.