Errors - Payable API

Every error is application/problem+json, following RFC 9457. This covers authentication, validation, rate limits, insufficient balance and unavailable dependencies. Never parse error text. Branch on:

status for HTTP flow (retry, login, 404)
code for product decisions, the stable identifier
errors[].field to highlight invalid form fields
requestId when contacting support

{
  "type": "https://docs.payable.run/errors/validation_error",
  "title": "Bad Request",
  "status": 400,
  "detail": "One or more request fields are invalid.",
  "instance": "/api/v1/clients",
  "code": "VALIDATION_ERROR",
  "requestId": "d8a19cda-1086-4b92-99c3-4ea116d72111",
  "errors": [{ "field": "email", "message": "email must be an email" }]
}

detail may be reworded or translated. code will not change.

HTTP status

Status	Meaning
`400`	Invalid parameters
`401`	Invalid or missing API key or token
`402`	Insufficient balance (live mode only)
`403`	The credential lacks permission or scope
`404`	Resource not found (or it belongs to the other mode)
`409`	State conflict: duplicate phone/CPF, or an `Idempotency-Key` reused with a different payload
`429`	Rate limit exceeded
`502`	An upstream integration failed
`503`	A required integration is not configured or is unavailable

Error codes

`code`	When
`VALIDATION_ERROR`	Invalid body, query or path parameter
`BAD_REQUEST`	Semantically invalid request
`UNAUTHORIZED`	Missing, invalid or expired token
`INSUFFICIENT_BALANCE`	Wallet cannot cover a live operation
`FORBIDDEN`	Missing role or scope
`RESOURCE_NOT_FOUND`	Does not exist, belongs to another organization, or is in the other mode
`CONFLICT`	Incompatible state, conflicting idempotency, or duplicate client
`RATE_LIMITED`	API key or IP limit reached
`MERCADO_PAGO_NOT_CONFIGURED`	Automatic PIX is unavailable for the organization
`UPSTREAM_ERROR`	Mercado Pago, OpenAI or storage failed to respond
`SERVICE_UNAVAILABLE`	A configured dependency cannot serve the operation
`INTERNAL_ERROR`	Unexpected failure, send the `requestId` to support

Retries

Use an Idempotency-Key on every mutation. Retry automatically only on 429, 502 and 503, keeping the same key, and honor Retry-After on 429. Do not retry 404, 409 or VALIDATION_ERROR without fixing the request.