Troubleshoot API and conformance failures

Use this page when a Conduit request returns an unexpected status, an error envelope, or a browser-visible failure. You will identify the response category, inspect the errors object without exposing tokens, apply the supported correction, and verify the original request again.

Before you begin

You need the request URL, HTTP method, response status, and response body. Use a test account and test content when reproducing a failure. Keep Authorization values and passwords out of logs, screenshots, and bug reports.

All API errors use an errors object. Its keys identify a field or resource, and each value is an array of messages. For example:

{
  "errors": {
    "token": ["is missing"]
  }
}

Diagnose the failure

The response is 401 Unauthorized

A protected request is missing a token, or login rejected the supplied credentials. Confirm that the request includes the exact header format Authorization: Token <jwt> and that the token came from registration or login. Do not send a bearer prefix.

curl --include \
  -H 'Authorization: Token YOUR_JWT' \
  https://api.realworld.show/api/user

If the response contains errors.token: ["is missing"], correct the header or authenticate before retrying. If login returns errors.credentials: ["invalid"], check the test account's email and password. A successful retry returns the protected resource instead of 401.

The response is 422 Unprocessable Entity

The request reached the API, but a field failed validation. Read each key in errors and correct the named input; do not treat a validation error as a transient network problem. Empty username, email, or password values are rejected, and invalid update values can also return 422.

{
  "errors": {
    "email": ["can't be blank"]
  }
}

Send the corrected JSON with the same method and endpoint. Confirm recovery by checking the success status and resource envelope documented for that operation.

The response is 409 Conflict

The registration request conflicts with an existing account. The tested cases return errors.username: ["has already been taken"] or errors.email: ["has already been taken"]. Use a new test username and email, or use login for the existing account. Confirm that registration returns 201 and a user response.

The response is 403 Forbidden

The token is valid, but the authenticated user does not own the resource or lacks the required permission. The conformance tests cover a second user attempting to update or delete another user's article or delete another user's comment. The response identifies the resource, for example errors.article: ["forbidden"].

Repeat the request with the owning user's token, or change the workflow so the current user acts only on resources they own. Confirm that the resource remains unchanged after the rejected request, then verify the authorized operation with the correct token.

The response is 404 Not Found

The requested slug, profile, or comment does not exist in the API's visible data. Check the path value and obtain the identifier from a successful list or create response. After an article is deleted, a follow-up GET /articles/{slug} returns 404 with errors.article: ["not found"]; that is the expected confirmation of deletion.

The browser shows a network or server failure

First inspect the browser's network request and determine whether the API returned a response. A 500 response should be represented as an error state while the application keeps its navigation and other usable controls visible. A timeout, connection refusal, or disconnected request has no API error envelope, so handle it as a transport failure and preserve the surrounding page state.

If the request is never available to the application because the browser reports a cross-origin policy failure, verify the backend's CORS handling and the Authorization header configuration in Configure CORS for separate frontend and backend origins. Then confirm that the request reaches the API and that the application still renders its navigation and primary content when a dependent request fails.

Verify a conformance failure

Compare the failing request with the OpenAPI operation and the Hurl assertion for that case. Check the status first, then the JSON path and message. For ownership cases, use two distinct test users and verify that the failed mutation did not change the resource. For deletion, expect 204 followed by 404 on a read of the same slug.

For frontend tests, a passing recovery means the page does not crash, its persistent navigation remains visible, and the affected form or control shows the error state or remains usable. The end-to-end error tests use these observable outcomes for server, timeout, connection-refused, and disconnected requests.

Next steps

Use Error envelope and HTTP status behavior for the shared response model, Authentication and token usage for token handling, or Run Hurl tests to compare an implementation with the conformance suite.