Errors

Every error response (4xx/5xx) follows RFC 7807 — the same shape, always:

{
  "type": "ERR_INTEGRATION_006",
  "title": "Método não disponível",
  "status": 422,
  "detail": "O método de pagamento informado não está habilitado no projeto.",
  "instance": "/api/v1/transactions"
}

Field	What it is
`type` / `errorCode`	The stable error code — use it in your code, not the message
`title`	Short human-readable title
`status`	HTTP status (repeated in the body)
`detail`	Explanation of what happened
`instance`	Path of the request that failed
`details`	Extras when present — e.g. `issues` with the invalid fields on validation errors

Handle errors by status + type. The messages (title/detail) may improve over time; the codes don’t change.

What to do with each status

Status	Meaning	What to do
`400`	Invalid payload (validation)	Don’t retry without fixing it. Check `details.issues` — it lists field by field what failed.
`401`	API key missing, invalid, or revoked	Check the `Authorization: Bearer sk_...` header and that the key wasn’t revoked in the Dashboard.
`403`	Authenticated, but no permission	Check the key type and the project mode (a sandbox project blocks `sk_live_`).
`404`	Resource not found	Wrong ID or from another project — the API doesn’t reveal other people’s resources.
`409`	`Idempotency-Key` in processing	Another request with the same key is in flight. Wait ~1s and retry with the same key — you get the replay. See Idempotency.
`422`	Semantic error	The payload is valid, but a business rule blocks it: method not available, amount above the project limit, an idempotency key reused with a different body. Fix the cause before retrying.
`429`	Rate limit	Wait for the `Retry-After` header (seconds) before retrying. Exponential backoff if it persists.
`500`	Internal error	Retry with backoff. If it persists, contact support with the `instance` and the time.
`503`	Processing temporarily unavailable or system under load	Transient — retry with backoff. On transaction creation, use an Idempotency-Key to retry without the risk of duplicating.

Codes you’ll encounter

`type`	Status	When it happens
`ERR_VALIDATION_001`	400	Invalid fields in the body/query (details in `details.issues`)
`ERR_AUTH_009`	401	Invalid or expired API key
`ERR_AUTHZ_001`	403	Key without the required permission for the resource
`ERR_TRANSACTION_001`	404	Transaction not found
`ERR_INTEGRATION_006`	422	Payment method not available on the project

Special case: HTTP 202 on creation

202 is not an error — it’s a partial success. The PIX was generated, but persistence is pending automatic reconciliation:

data.id comes back null; use data.externalId as the reference
The pixCode is valid and payable — deliver it to the buyer as usual
The transaction appears in the listing within a few minutes, after reconciliation

Timeouts

Transaction creation can take up to 30 seconds in the worst case. Set your HTTP client’s timeout above that (the SDK uses 35s) and, when retrying after a timeout, use the same Idempotency-Key — if creation completed, you get the replay instead of a duplicate payment.

Getting Started

Core concepts

Integration methods

Webhooks

Using Bob

API fundamentals

What to do with each status

Codes you’ll encounter

Special case: HTTP 202 on creation

Timeouts

Next steps

Idempotency

Configure webhooks

​What to do with each status

​Codes you’ll encounter

​Special case: HTTP 202 on creation

​Timeouts

​Next steps

Idempotency

Configure webhooks

What to do with each status

Codes you’ll encounter

Special case: HTTP 202 on creation

Timeouts

Next steps