> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moneydev.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros

> O objeto de erro da API MoneyDev, códigos de status HTTP, tipos de erro e como usar os IDs de requisição.

Quando uma requisição `/v1` falha, a MoneyDev retorna um status `4xx` ou `5xx` e um corpo JSON com um único objeto `error`.

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_customer_id",
    "message": "O ID do cliente é inválido.",
    "param": "customer_id",
    "request_id": "req-a1b2c3d4"
  }
}
```

<ResponseField name="error.type" type="string">
  Categoria geral do erro. Veja os [tipos](#tipos-de-erro) abaixo.
</ResponseField>

<ResponseField name="error.code" type="string">
  Uma string estável e específica, legível por máquina, ex. `customer_email_already_exists`. Faça o seu tratamento com base nela.
</ResponseField>

<ResponseField name="error.message" type="string">
  Explicação legível, em português. Pode ser mostrada ao usuário final quando fizer sentido, mas registre em log — não faça correspondência de texto por ela.
</ResponseField>

<ResponseField name="error.param" type="string">
  Presente quando o erro está ligado a um campo de entrada. Com ponto para campos aninhados, ex. `default_offer.amount_minor`.
</ResponseField>

<ResponseField name="error.request_id" type="string">
  Identificador desta requisição, também retornado no header `X-Request-Id`. Informe ao acionar o suporte.
</ResponseField>

<Note>
  `POST /oauth/token` não usa este formato. As falhas dele seguem a spec OAuth: `{ "error": "...", "error_description": "..." }`. Veja [Autenticação](/authentication#erros-do-endpoint-de-token).
</Note>

## Tipos de erro

| `type` | Status | Significado |
| - | - | - |
| `authentication_error` | `401` | Token de acesso ausente, inválido, expirado ou revogado |
| `authorization_error` | `403` | O token é válido mas não tem o escopo exigido |
| `invalid_request_error` | `400` | Requisição malformada — JSON inválido, validação falhou, um ID ou cursor não interpretável |
| `not_found_error` | `404` | O recurso não existe ou não é visível para a sua conta |
| `conflict_error` | `409` | A requisição colide com o estado atual, ex. um valor único duplicado |
| `api_error` | `500` | Algo falhou do nosso lado. Pode repetir com backoff |

## Códigos comuns

| `code` | Tipo | Observações |
| - | - | - |
| `missing_access_token` | `authentication_error` | Sem header `Authorization: Bearer` |
| `invalid_access_token` | `authentication_error` | Token recusado |
| `insufficient_scope` | `authorization_error` | Token sem o escopo do endpoint |
| `invalid_request` | `invalid_request_error` | Validação de schema falhou; `param` aponta o campo |
| `invalid_cursor` | `invalid_request_error` | `starting_after` não é um ID válido para esta lista |
| `customer_email_already_exists` | `conflict_error` | Já existe um cliente com esse e-mail na sua conta |
| `checkout_external_id_already_exists` | `conflict_error` | `external_id` já usado em outro checkout |

Códigos específicos de recurso (`customer_not_found`, `offer_not_found`, `recurring_checkout_not_supported`, …) estão listados em cada página de endpoint.

## Erros de validação

Corpos de requisição passam por validação de schema antes de qualquer processamento. Uma falha retorna `400` com `code: "invalid_request"` e `param` no caminho do campo problemático:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "body/email must match format \"email\"",
    "param": "email",
    "request_id": "req-a1b2c3d4"
  }
}
```

## Repetição

Repita `500` (`api_error`) e o `503` do OAuth (`temporarily_unavailable`) com backoff exponencial. Não repita `4xx` cegamente — corrija a requisição primeiro. Para repetir `POST /v1/checkouts` com segurança, defina um `external_id`: uma repetição com o mesmo valor retorna `checkout_external_id_already_exists` em vez de criar uma segunda sessão.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.