Schemathesis "Undocumented HTTP status code" in CI

By Kaveh Alemi·Latchkey

Schemathesis compares each response status against the ones your schema documents for that operation. A status the schema does not list (often a 400 or 422 the code returns but the spec omits) fails the status_code_conformance check.

What this error means

The run reports "Undocumented HTTP status code" with "Received: 422" and "Documented: 200, 404", naming the operation whose responses the schema does not fully describe.

1. Undocumented HTTP status code
    Received: 422
    Documented: 200, 404
    GET /users/{id}

Common causes

The schema omits a status the code returns

The endpoint returns 422 (or 400/409) on some input, but the OpenAPI responses map does not list it, so the response does not conform.

The API returns an unexpected status

A bug or middleware returns a status the operation should never emit, revealing a mismatch between the spec and behavior.

How to fix it

Document the real responses in the schema

1. Decide whether the status is intended for that operation.
2. If yes, add it to the operation's responses in the OpenAPI document.
3. Re-run so the response conforms to the documented set.

responses:
  '200': { description: OK }
  '404': { description: Not found }
  '422': { description: Validation error }

Fix the handler if the status is wrong

If the operation should never return that status, correct the code so it returns a documented one.

How to prevent it

• Keep the OpenAPI responses map in sync with what handlers return.
• Document validation and error statuses, not just the happy path.
• Run status conformance checks in CI so drift is caught early.

Frequently asked questions

Related guides

References

• GitHub Actions documentation