API errors

Unprocessable entity

The request is well formed and valid, but the operation it asks for cannot be carried out. The detail field explains why.

422application/problem+json

What it means

The request parsed correctly and every field passed validation, but the operation itself was refused: the resource does not support it, or a value breaks a business rule rather than a format. The refusal is explained in detail.

One 422 case has its own type: replaying an X-Idempotency-Key with a different request body returns idempotency key reused instead.

422 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/unprocessable-entity",
  "title": "Unprocessable entity",
  "status": 422,
  "detail": "Insufficient balance"
}

How to handle it

Read detail. It names the rule the operation broke.
Do not retry unchanged. The answer stays the same until the request or the underlying data changes.
If the refusal depends on what the resource supports or the state it is in, fetch the resource first and adjust the request to match.

Errors reference Idempotency, in the rate limits guide

What it means

How to handle it

Related