Errors

Every failed request returns the same JSON envelope:

{
  "errors": [
    {
      "code": "INVALID_TOKEN",
      "message": "The personal API token is not valid.",
      "details": {},
      "request_id": "F8x2kQ9vXc1AAAAB"
    }
  ]
}

Branch on code; it is stable. message is English text for developers and can change.
details carries extra context for some codes, such as required_scope or retry_after_seconds.
request_id matches the x-request-id response header. Include it when you contact support.

Codes

Status	Code	Meaning
400	`BAD_REQUEST`	The query string or body is malformed, a query parameter has an invalid value (`details.parameter`), or the body has a field the operation does not accept (`details.field`).
400	`IDEMPOTENCY_KEY_INVALID`	A create has no `Idempotency-Key` header, or the key is longer than 128 characters or has other characters. See Idempotency.
401	`UNAUTHENTICATED`	The `Authorization: Bearer` header is missing.
401	`INVALID_TOKEN`	The token is malformed, unknown, or its secret is wrong.
401	`TOKEN_EXPIRED`	The token expired. Create a new one.
401	`TOKEN_REVOKED`	The token was revoked. Create a new one.
403	`PLAN_REQUIRED`	The account does not have an active Pro or Premium plan.
403	`INSUFFICIENT_SCOPE`	The token does not grant the scope in `details.required_scope`.
403	`PIX_UNAVAILABLE`	Pix payments are not available for the account.
403	`PREMIUM_REQUIRED`	Starting a Pix needs the Premium plan. `details.url` opens the plan page.
404	`NOT_FOUND`	The path does not exist, or the space or resource does not exist or is not accessible to you.
406	`NOT_ACCEPTABLE`	The `Accept` header excludes `application/json`.
409	`IDEMPOTENCY_CONFLICT`	The `Idempotency-Key` was already used in the account for a different transaction or Pix.
409	`IMMUTABLE_PROVIDER_FIELD`	An edit changes a field that the bank owns. `details.field` names it.
409	`TRANSACTION_CONFLICT`	Another record depends on the transaction, such as a paid installment. `details.reason` names it.
409	`PIX_START_FAILED`	The Pix could not start with this `Idempotency-Key`, for example because its draft expired. Send a new key.
422	`VALIDATION_FAILED`	The body has invalid values. `details.errors` lists each `field` and `message`.
422	`AMBIGUOUS_PIX_KEY`	The Pix key can be a CPF or a phone. Send the request again with `key_type`.
422	`PIX_MONTHLY_LIMIT_REACHED`	The plan’s monthly Pix limit is spent. `details.limit` and `details.renews_on` say when it renews.
422	`CPF_REQUIRED`	The Visor profile has no CPF, which a Pix needs.
422	`BANK_REQUIRED`	Send the `bank` the Pix comes from. `details.banks` lists suggestions.
422	`BANK_NOT_FOUND`	Pix through Visor is not available from that bank. `details.banks` lists suggestions.
429	`RATE_LIMITED`	Too many requests. See Rate limits.
500	`INTERNAL_ERROR`	An unexpected error occurred. Retry later.

Get started

Essentials

Codes

​Codes

Codes