Testing de APIs

Referencia de códigos de estado HTTP

Todos los códigos de estado HTTP con qué verificar y qué bugs buscar.

Se ejecuta íntegramente en tu navegador Sin registro

Search codes

Hide rare / WebDAV codes

62 of 62 codes

1xx InformationalInterim responses; the final response follows.

100

Continue

rareRFC 9110 §15.2.1

The server received the request headers and the client should send the body.

When to return it: Only in reply to a request with Expect: 100-continue, typically before a large upload.
What to verify: Send a large upload with Expect: 100-continue and confirm the server either answers 100 then the final status, or rejects early (e.g. 413, 401) without reading the body. Most HTTP clients handle this transparently.

101

Switching Protocols

RFC 9110 §15.2.2

The server is switching to the protocol named in the Upgrade header.

When to return it: WebSocket handshakes (Upgrade: websocket) over HTTP/1.1.
What to verify: For WebSocket endpoints, verify 101 with Upgrade and Connection headers and a correct Sec-WebSocket-Accept. Check that unauthenticated upgrade requests are rejected with 401/403 rather than upgraded.

Common bugs

WebSocket upgrade accepted without authentication or Origin checks.

102

Processing

rareRFC 2518 (WebDAV; removed in RFC 4918)

The server has accepted the request but has not completed it yet.

When to return it: Legacy WebDAV only. Modern APIs use 202 Accepted with a status resource instead.
What to verify: Rarely seen. If an API emits it, check the client does not treat it as the final response.

103

Early Hints

rareRFC 8297

Preliminary Link headers so the browser can preload resources while the server prepares the response.

When to return it: HTML pages served through CDNs that support Early Hints; not used by JSON APIs.
What to verify: Verify the final response still carries the headers that matter (103 headers are hints only) and that hinted resources exist.

2xx SuccessThe request was received, understood and accepted.

200

OK

RFC 9110 §15.3.1

The request succeeded and the body contains the result.

When to return it: Successful GET, successful PUT/PATCH that returns the updated resource, or an action that returns a result.
What to verify: Assert the status AND the body: schema, values and Content-Type. A 200 alone proves very little. Check that error conditions never come back as 200.

Common bugs

200 with an error body such as {"success": false, "error": "..."}; monitoring and clients treat it as success.
200 for a POST that created a resource where 201 + Location is documented.
200 with an empty body where the schema promises data.

201

Created

RFC 9110 §15.3.2

The request created a new resource.

When to return it: Successful POST (or PUT to a new URI) that creates a resource.
What to verify: Verify the Location header points to the new resource, the body (if any) contains the server-generated id, and a follow-up GET returns the same data.

Common bugs

Missing or relative-but-wrong Location header.
Resource returned before it is actually persisted (GET right after returns 404).

202

Accepted

RFC 9110 §15.3.3

The request was accepted for processing, which has not finished.

When to return it: Asynchronous jobs: exports, bulk imports, long-running operations.
What to verify: Verify the response tells you how to track the job (a status URL in Location or the body). Poll it to completion and test the failure path of the job too.

Common bugs

No way to find out whether the job later failed.
Job status endpoint reachable by other users.

203

Non-Authoritative Information

rareRFC 9110 §15.3.4

Success, but the payload was modified by a transforming proxy.

When to return it: Set by intermediaries, not by origin APIs.
What to verify: If you see it, something between client and server is rewriting responses. Compare with a direct call to the origin.

204

No Content

RFC 9110 §15.3.5

Success with no response body.

When to return it: Successful DELETE, or PUT/PATCH where the API does not return the resource.
What to verify: Assert the body is truly empty (Content-Length: 0 or absent body). Client code that calls response.json() on a 204 will throw, so check consumers handle it.

Common bugs

204 sent with a body (some proxies drop it, others hang).
Client crashes parsing an empty body as JSON.

205

Reset Content

rareRFC 9110 §15.3.6

Success; the client should reset the document view (e.g. clear a form).

When to return it: Rare; form-submission UIs.
What to verify: Must not contain a body. Rarely used by REST APIs.

206

Partial Content

RFC 9110 §15.3.7

The body contains only the byte range(s) requested with a Range header.

When to return it: Resumable downloads and media streaming.
What to verify: Request Range: bytes=0-99 and verify 206, Content-Range: bytes 0-99/<total> and exactly 100 bytes. Test an unsatisfiable range (expect 416) and multiple ranges.

Common bugs

Content-Range total wrong, breaking resumed downloads.
Server ignores Range and returns 200 with the full file while advertising Accept-Ranges: bytes.

207

Multi-Status

RFC 4918 §11.1 (WebDAV)

The body contains separate status codes for multiple sub-operations.

When to return it: Batch operations where items can succeed or fail independently.
What to verify: Never stop at the top-level 207: assert the status of every item in the body, and include a batch where some items fail.

Common bugs

Tests pass because they only check the outer 207 while individual items failed.

208

Already Reported

rareRFC 5842 (WebDAV)

Members of a binding were already listed earlier in the same 207 response.

When to return it: WebDAV bindings only.
What to verify: Not expected from REST APIs.

226

IM Used

rareRFC 3229

The response is the result of instance manipulations (delta encoding).

When to return it: Delta encoding; practically unused.
What to verify: Not expected from REST APIs.

3xx RedirectionFurther action (usually following a Location) is needed.

300

Multiple Choices

rareRFC 9110 §15.4.1

The resource has several representations and the client should choose.

When to return it: Rare; content negotiation without a server-side choice.
What to verify: Rare in APIs. If returned, check the body lists the choices.

301

Moved Permanently

RFC 9110 §15.4.2

The resource has a new permanent URI given in Location.

When to return it: Permanent URL changes for GET resources (e.g. HTTP to HTTPS, old to new paths).
What to verify: Verify Location is absolute and correct and that clients follow it. Note that clients may change POST to GET when following 301; APIs that move write endpoints should use 308.

Common bugs

POST silently turned into GET after a 301, losing the body.
Redirect loop between http/https or trailing-slash variants.

302

Found

RFC 9110 §15.4.3

The resource is temporarily at the URI in Location.

When to return it: Temporary redirects, commonly after login in browser flows.
What to verify: APIs should rarely return 302. A JSON API answering an expired session with 302 to an HTML login page is a classic bug: test clients expecting JSON get HTML.

Common bugs

API redirects unauthenticated calls to an HTML login page instead of returning 401.
Open redirect: Location built from an unvalidated query parameter.

303

See Other

RFC 9110 §15.4.4

Get the result from the URI in Location using GET.

When to return it: After a POST that started a job or created something, to point at the result (POST-redirect-GET).
What to verify: Verify the client issues a GET to Location and that it returns the expected result.

304

Not Modified

RFC 9110 §15.4.5

The cached copy is still valid; no body is sent.

When to return it: Conditional GET with If-None-Match or If-Modified-Since when nothing changed.
What to verify: GET once, take the ETag, repeat with If-None-Match: <etag> and expect 304 with no body. Change the resource and expect 200 with a new ETag.

Common bugs

ETag changes on every request (e.g. includes a timestamp), so 304 never happens.
Stale 304 after the resource changed.

305

Use Proxy

rareRFC 9110 §15.4.6 (deprecated)

Deprecated; clients must not honour it for security reasons.

When to return it: Never.
What to verify: Should never be returned.

307

Temporary Redirect

RFC 9110 §15.4.8

Temporary redirect that keeps the method and body.

When to return it: Temporary moves of endpoints that receive POST/PUT; also used by browsers for HSTS internal redirects.
What to verify: Verify the method and body are preserved when following it and that Authorization is not forwarded to a different host.

308

Permanent Redirect

RFC 9110 §15.4.9

Permanent redirect that keeps the method and body.

When to return it: Permanent moves of API endpoints, including write endpoints.
What to verify: Same checks as 301, plus confirm POST stays POST with the same body after the redirect.

4xx Client errorThe request is wrong; retrying it unchanged will fail again.

400

Bad Request

RFC 9110 §15.5.1

The server cannot process the request because it is malformed.

When to return it: Unparseable JSON, wrong types, missing required parameters, invalid query values.
What to verify: Send malformed JSON, wrong types and missing fields. Expect 400 (or 422) with an error body that names the field. It must never be a 500.

Common bugs

500 Internal Server Error for invalid input (unhandled exception).
Generic message with no field name, making the error unactionable.
Error body leaks stack traces or SQL.

401

Unauthorized

RFC 9110 §15.5.2

Authentication is missing or invalid. Despite the name, it means "unauthenticated".

When to return it: No credentials, malformed credentials, expired or revoked tokens.
What to verify: Test no token, malformed token, expired token, token signed with the wrong key and a revoked token. Expect 401 with a WWW-Authenticate header and no resource data.

Common bugs

403 returned where 401 is correct (or the reverse).
Missing WWW-Authenticate header.
Expired tokens still accepted.

402

Payment Required

rareRFC 9110 §15.5.3 (reserved)

Reserved for future use; some APIs use it for billing problems.

When to return it: Non-standard: quota or subscription exhausted, if the API documents it.
What to verify: Only test if documented. Check the error body explains what to do.

403

Forbidden

RFC 9110 §15.5.4

The client is authenticated (or authentication would not help) but is not allowed to do this.

When to return it: Missing role or scope, accessing another tenant's data, blocked IPs.
What to verify: Use a valid token from a user without the permission and confirm 403 with no side effects. Check object-level authorisation: user A must not read or modify user B's resources by changing an id.

Common bugs

Broken object-level authorisation (BOLA/IDOR): 200 with another user's data.
Action performed even though 403 is returned.

404

Not Found

RFC 9110 §15.5.5

The server has no resource at this URI (or will not reveal that it exists).

When to return it: Unknown ids or paths. Also acceptable instead of 403 to hide the existence of resources.
What to verify: Request a non-existent id, a deleted id and a malformed path. Expect 404 with a consistent error body. An empty collection should be 200 with [], not 404.

Common bugs

404 for an empty list.
500 when the id has the wrong format.
Different responses for "exists but forbidden" and "missing" that allow enumeration.

405

Method Not Allowed

RFC 9110 §15.5.6

The resource exists but does not support this method.

When to return it: e.g. DELETE on a read-only collection.
What to verify: Send unsupported methods and verify 405 with an Allow header listing the supported methods.

Common bugs

404 or 500 instead of 405.
Missing Allow header.

406

Not Acceptable

RFC 9110 §15.5.7

No representation matches the Accept headers.

When to return it: Client asks for a media type the API cannot produce (e.g. Accept: application/xml on a JSON-only API).
What to verify: Send Accept: application/xml and check for 406 or documented fallback to JSON.

407

Proxy Authentication Required

rareRFC 9110 §15.5.8

Like 401 but for a proxy between client and server.

When to return it: Corporate proxies.
What to verify: Usually an environment problem in CI rather than an API defect. Configure proxy credentials.

408

Request Timeout

rareRFC 9110 §15.5.9

The server timed out waiting for the client to send the request.

When to return it: Slow or stalled uploads; idle connections.
What to verify: Not the same as a slow server (that is 504 at a gateway, or a client-side timeout). Simulate a slow upload if relevant.

409

Conflict

RFC 9110 §15.5.10

The request conflicts with the current state of the resource.

When to return it: Duplicate unique values (email already registered), version conflicts, invalid state transitions.
What to verify: Create a duplicate (same email/SKU) and expect 409 with a clear message. Fire two concurrent updates and check one wins cleanly.

Common bugs

500 from an unhandled unique-constraint violation.
Duplicate records created under concurrency.

410

Gone

RFC 9110 §15.5.11

The resource was intentionally removed and will not come back.

When to return it: Retired API versions or permanently deleted resources.
What to verify: For sunset API versions, verify 410 after the sunset date and that the error points to the replacement.

411

Length Required

rareRFC 9110 §15.5.12

The server requires a Content-Length header.

When to return it: Servers that refuse chunked uploads.
What to verify: Send a body with chunked transfer encoding and no Content-Length if the API documents this restriction.

412

Precondition Failed

RFC 9110 §15.5.13

A conditional header such as If-Match did not match.

When to return it: Optimistic concurrency: PUT/PATCH with If-Match carrying a stale ETag.
What to verify: GET (save ETag), modify the resource elsewhere, then PUT with If-Match: <old etag>. Expect 412 and no change.

Common bugs

If-Match ignored, so lost updates happen silently.

413

Content Too Large

RFC 9110 §15.5.14

The request body is larger than the server allows (formerly "Payload Too Large").

When to return it: Uploads or JSON bodies over the documented limit.
What to verify: Send a body just over the limit. Expect 413 quickly, not a timeout, a dropped connection or a 500.

Common bugs

Limit enforced only at the proxy, producing an HTML error page instead of JSON.

414

URI Too Long

RFC 9110 §15.5.15

The request URI is longer than the server will interpret.

When to return it: Very long query strings (huge filters or id lists).
What to verify: Send a query string of several kilobytes. If filters can grow large, the API should offer a POST search endpoint.

415

Unsupported Media Type

RFC 9110 §15.5.16

The request body's Content-Type is not supported.

When to return it: Body sent as text/plain or XML to a JSON-only endpoint; missing Content-Type.
What to verify: Send a valid JSON body with Content-Type: text/plain and with no Content-Type. Expect 415 (or a documented 400).

Common bugs

Body silently ignored and the request processed with defaults.

416

Range Not Satisfiable

rareRFC 9110 §15.5.17

The requested Range cannot be served.

When to return it: Range starts beyond the end of the file.
What to verify: Request a range past the end and expect 416 with Content-Range: bytes */<total>.

417

Expectation Failed

rareRFC 9110 §15.5.18

The Expect header could not be met.

When to return it: Unsupported Expect values.
What to verify: Rare. Send an unknown Expect value if you are testing an HTTP server itself.

418

I'm a teapot

rareRFC 2324 (April Fools); reserved as unused by RFC 9110 §15.5.19

A joke code from the Hyper Text Coffee Pot Control Protocol.

When to return it: Never in production. Some services use it as a deliberately odd response to bots.
What to verify: If a real API returns 418, file a bug or confirm it is a documented anti-bot response. Useful as an "unexpected status" in client error-handling tests.

421

Misdirected Request

rareRFC 9110 §15.5.20

The request reached a server that cannot produce a response for this origin.

When to return it: HTTP/2 connection reuse across hostnames with mismatched certificates.
What to verify: Seen with shared CDN/TLS setups. Usually an infrastructure configuration issue.

422

Unprocessable Content

RFC 9110 §15.5.21

The body is syntactically valid but semantically invalid.

When to return it: Validation failures: end date before start date, unknown enum value, business rule violations.
What to verify: Check the API is consistent: one convention for validation errors (400 or 422) across all endpoints, with a machine-readable list of field errors.

Common bugs

Mix of 400 and 422 for the same kind of error across endpoints.
Only the first validation error reported.

423

Locked

rareRFC 4918 §11.3 (WebDAV)

The resource is locked.

When to return it: Locked documents or accounts, if documented.
What to verify: If used for locked accounts, check the message does not reveal whether the account exists.

424

Failed Dependency

rareRFC 4918 §11.4 (WebDAV)

The request failed because a previous request it depended on failed.

When to return it: Items inside a batch/multi-status response.
What to verify: Check dependent items in a batch report 424 rather than a misleading success.

425

Too Early

rareRFC 8470

The server will not process a request that might be replayed (TLS 1.3 early data).

When to return it: Non-idempotent requests received as TLS 0-RTT early data.
What to verify: Relevant for edge/CDN setups with 0-RTT enabled: non-idempotent requests must not be processed from early data.

426

Upgrade Required

rareRFC 9110 §15.5.22

The client must switch to a different protocol named in Upgrade.

When to return it: e.g. requiring a newer protocol version.
What to verify: Verify the Upgrade header names the required protocol.

428

Precondition Required

RFC 6585 §3

The server requires the request to be conditional (e.g. include If-Match).

When to return it: APIs that enforce optimistic locking on updates.
What to verify: Send PUT/PATCH without If-Match and expect 428; with a current ETag expect success; with a stale one expect 412.

429

Too Many Requests

RFC 6585 §4

The client has sent too many requests in a given time (rate limiting).

When to return it: Rate or quota limits exceeded.
What to verify: Exceed the limit in a loop. Expect 429 with Retry-After, accurate rate limit headers, and recovery after the window. Confirm limits are per client/key and cannot be bypassed by changing headers like X-Forwarded-For.

Common bugs

No Retry-After header.
Limit keyed on a spoofable header.
503 or 500 used for throttling.

431

Request Header Fields Too Large

RFC 6585 §5

Headers (or a single header) are too large.

When to return it: Oversized cookies or tokens.
What to verify: Send a very large cookie or Authorization header. Large JWTs with many claims can trigger this in production.

451

Unavailable For Legal Reasons

rareRFC 7725

The resource is unavailable because of a legal demand.

When to return it: Geo-blocked or legally removed content.
What to verify: If used, verify a Link header with rel="blocked-by" where appropriate and that the reason is explained.

5xx Server errorThe server failed to fulfil a valid request.

500

Internal Server Error

RFC 9110 §15.6.1

An unexpected condition prevented the server from fulfilling the request.

When to return it: Genuinely unexpected failures only. Never as a response to bad client input.
What to verify: Any 500 you can trigger with crafted input is a bug: the input should get a 4xx. Check that the body is a generic error with a correlation id, not a stack trace.

Common bugs

500 for validation errors, malformed JSON or a wrong id format.
Stack traces, SQL or file paths in the body.
Partial writes left behind after the failure.

501

Not Implemented

RFC 9110 §15.6.2

The server does not support the functionality required (often an unknown method).

When to return it: Methods the server does not recognise at all.
What to verify: For a known method on a resource that does not allow it, 405 is correct, not 501.

502

Bad Gateway

RFC 9110 §15.6.3

A gateway or proxy got an invalid response from the upstream server.

When to return it: Set by load balancers/gateways when the app crashes or closes the connection.
What to verify: Usually means the application process died or rejected the connection. Correlate with app logs; check the gateway returns a JSON error body for API clients.

503

Service Unavailable

RFC 9110 §15.6.4

The server is temporarily unable to handle the request (overload or maintenance).

When to return it: Maintenance windows, overload shedding, dependency outages; health checks reporting unhealthy.
What to verify: Check Retry-After is present during maintenance and that clients back off. Verify health endpoints return 503 when a critical dependency is down.

Common bugs

Health check returns 200 while the database is down.

504

Gateway Timeout

RFC 9110 §15.6.5

A gateway or proxy did not get a timely response from upstream.

When to return it: Upstream exceeds the gateway timeout.
What to verify: Find slow paths (large exports, unindexed filters). The operation may still complete on the server after the 504, so check for duplicate side effects on retry.

Common bugs

Client retries a POST after 504 and creates duplicates (no idempotency key).

505

HTTP Version Not Supported

rareRFC 9110 §15.6.6

The HTTP version used in the request is not supported.

When to return it: Protocol-level mismatch.
What to verify: Rare; only relevant when testing HTTP servers or proxies.

506

Variant Also Negotiates

rareRFC 2295

Server misconfiguration in transparent content negotiation.

When to return it: Practically never.
What to verify: Indicates a server configuration error.

507

Insufficient Storage

rareRFC 4918 §11.5 (WebDAV)

The server cannot store the representation needed to complete the request.

When to return it: Storage quota or disk full, if the API documents it.
What to verify: If used for user quotas, confirm the message is clear; quotas exceeded by the user are arguably 4xx.

508

Loop Detected

rareRFC 5842 (WebDAV)

The server detected an infinite loop while processing.

When to return it: WebDAV bindings.
What to verify: Not expected from REST APIs.

510

Not Extended

rareRFC 2774 (historic)

Further extensions to the request are required.

When to return it: Obsolete.
What to verify: Should not appear in modern APIs.

511

Network Authentication Required

rareRFC 6585 §6

The client must authenticate to gain network access (captive portals).

When to return it: Captive portals on public Wi-Fi, not origin servers.
What to verify: If tests in CI or on a device suddenly see 511 or HTML, the network is intercepting traffic.

Acerca de esta herramienta

Los códigos de estado forman parte del contrato de una API, y muchos defectos de API son simplemente el código equivocado: un 200 que envuelve un mensaje de error, un 500 ante una entrada no válida, un 404 para una lista vacía o un 403 donde corresponde un 401. Esta referencia cubre los códigos definidos en RFC 9110 más los de WebDAV y otras RFC que encontrarás, como 422, 425, 429 y 451, y el reservado 418. Para cada uno explica qué significa, cuándo debe devolverlo una API, qué debe comprobar un tester (cabeceras que deben acompañarlo, efectos secundarios que no deben producirse) y los defectos que suelen aparecer a su alrededor. Cada código tiene su propio ancla, así que /tools/http-status-codes#429 enlaza directamente con él.

Cómo usarla

Escribe un código (por ejemplo 4 o 42) para saltar a los códigos coincidentes, o busca palabras como «rate limit», «ETag» o «validation».
Filtra por clase (de 1xx a 5xx) y oculta los códigos poco frecuentes o exclusivos de WebDAV para centrarte en los que usan las APIs REST.
Usa las notas “What to verify” y “Common bugs” como checklist cuando escribas assertions o revises el diseño de una API.

Preguntas frecuentes: Referencia de códigos de estado HTTP

¿Cuál es la diferencia entre 401 y 403?

401 significa que la petición no está autenticada: las credenciales faltan, no son válidas o han caducado, y la respuesta debe incluir WWW-Authenticate. 403 significa que el servidor sabe quién eres (o que autenticarse no ayudaría) y no tienes permiso para hacer eso.

¿Los errores de validación deben ser 400 o 422?

Se usan ambos. 400 encaja con peticiones mal formadas (JSON que no se puede parsear, tipos incorrectos); 422 encaja con peticiones bien formadas que incumplen reglas semánticas. Lo importante es que una API aplique una única convención de forma coherente y nunca devuelva 500 ante una entrada incorrecta.

¿Está mal devolver 200 con un error en el body?

En APIs REST, sí. Los clientes, los reintentos, la monitorización y las cachés dependen del código de estado, así que un error disfrazado de 200 se trata como un éxito. GraphQL es la excepción notable: a menudo devuelve 200 con un array errors, así que ahí haz las assertions sobre el body.