Skip to content

Resolve request validation errors

Use a 422 response to find the invalid field and correct the request shape or value.

Updated

Read a 422 response

Threetone returns 422 Unprocessable Entity when FastAPI cannot validate request input. The response has a detail array. Each item contains:

  • loc: where the invalid value was found, such as body, query, or path, followed by the field name.
  • msg: a human-readable explanation.
  • type: the validation rule that failed.

Start with loc. It points to the part of the request that must change.

Correct the request

Check the following before sending it again:

  1. The HTTP method and /v1/... path match the operation.
  2. JSON requests include Content-Type: application/json and contain valid JSON.
  3. Required fields are present and field names use the documented spelling.
  4. Numbers, booleans, arrays, and objects use the expected JSON types.
  5. Enum values and query parameters satisfy the allowed values and ranges.

For example, the agent list endpoint accepts page_size values from 1 through 100. A value outside that range produces a validation error whose loc identifies query and page_size.

Do not retry the unchanged request. Fix the indicated value first, then send a new request and retain its X-Request-Id if it still fails.

Related articles

Resolve API access errors

Diagnose 401 and 403 responses from API key authentication and authorization checks.

Handle rate limits and server errors

Back off after 429 responses and retry safe operations carefully after temporary server failures.

Create and revoke API keys

Create a scoped API key, copy its secret once, and revoke it when it is no longer needed.