Error envelope and HTTP status behavior
Parse Conduit errors and choose a recovery action for common HTTP status codes.
Conduit reports request failures with an HTTP status and, for documented validation and resource errors, an errors object. Each key identifies a field or failure category, and each value is an array of human-readable messages. Parse the status first, then inspect every key in errors so your client can show or log all applicable problems.
Read the error envelope
The OpenAPI GenericErrorModel requires errors and allows any key to map to an array of strings. For example, an invalid registration field can produce:
{
"errors": {
"username": ["can't be blank"]
}
}The key is not always a request-body field. Authentication failures use keys such as token or credentials, and resource authorization can use resource.
Keep the original status and the complete errors object available to the caller. A message such as can't be blank is useful for a form, while is missing indicates that the request did not supply the required authentication material.
Status codes and recovery
| Status | Meaning in Conduit | Typical response | Recovery |
|---|---|---|---|
401 | Authentication is missing or invalid. | errors.token: ["is missing"] or errors.credentials: ["invalid"] | Supply a valid Authorization: Token <jwt> header, or authenticate again with valid credentials. |
403 | The authenticated user cannot perform the operation. | A resource permission error | Stop retrying unchanged. Check that the resource belongs to the authenticated user. |
404 | The requested resource cannot be found. | A not-found error | Check the slug, username, or comment id, then request the resource again. |
409 | The request conflicts with an existing resource. | errors.username or errors.email with has already been taken | Change the conflicting value or use the existing account. |
422 | The request fails validation or has an invalid parameter. | errors.field: ["can't be blank"] | Correct the named field or parameter and send the request again. |
The API can also return success-specific statuses such as 201 Created, 204 No Content, and 200 OK; do not treat a successful empty body such as 204 as an error.
Handle authentication errors
The error test suite verifies that a request without a token to GET /user returns 401 and errors.token[0] is is missing. A login with the wrong password also returns 401, with errors.credentials[0] set to invalid. These cases require different user actions: add or restore the Token header for the first case, and ask for valid credentials for the second.
curl -i "https://api.realworld.show/api/user"curl -i "https://api.realworld.show/api/users/login" \
-H "Content-Type: application/json" \
-d '{"user":{"email":"reader@example.com","password":"wrong-password"}}'Do not put a token in a query parameter or silently retry an unauthorized request with a different identity. See Authentication and token usage for the header format.
Handle validation and conflict errors
Registration with an empty username, email, or password returns 422; the corresponding key contains can't be blank. Registering an already-used username or email returns 409 and identifies the conflicting field with has already been taken.
For a client form, map each key to its field when the key matches a field name. Preserve unknown keys for a general error message because the contract permits additional keys. After changing the request, confirm that the endpoint returns its documented success status rather than assuming that a network response alone means the change succeeded.
Handle ownership and missing resources
A 403 means authentication succeeded but the authenticated user lacks permission, such as attempting to update or delete an article owned by someone else. Re-authenticating as the same user will not fix that condition. A 404 means the identifier cannot be resolved; verify the article slug, profile username, or comment id before retrying.
For endpoint-specific status coverage, use the Endpoint index and then open the resource guide for the request you are implementing. For response shapes beyond errors, see Response envelopes and resource models.