---
title: "Errores"
description: "Envelope de error público, catálogo de códigos HTTP/retryable y reglas de no filtración de recursos ajenos."
---

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

# Errores

# Errores

Todos los endpoints usan un envelope estable. El status HTTP describe la clase del resultado; `error.code` es el identificador que debe usar el cliente para tomar decisiones.

## Formato

```json
{
  "error": {
"code": "payment_method_not_found",
"message": "El método de pago solicitado no existe o no está habilitado para esta API key.",
"category": "validation",
"retryable": false,
"request_id": "req_019f704f89d77e83",
"details": {}
  }
}
```

| Campo        | Uso                                                         |
| ------------ | ----------------------------------------------------------- |
| `code`       | Identificador estable para lógica del cliente.              |
| `message`    | Explicación legible; no debe parsearse.                     |
| `category`   | Grupo general del error.                                    |
| `retryable`  | Indica si repetir podría funcionar sin corregir el request. |
| `request_id` | Correlación para logs y soporte.                            |
| `details`    | Información estructurada y no sensible, cuando aplica.      |

Un error de validación puede incluir detalles:

```json
{
  "error": {
"code": "invalid_request",
"message": "La solicitud no cumple el contrato.",
"category": "validation",
"retryable": false,
"request_id": "req_019f704f89d77e83",
"details": {
  "fields": [
    {
      "path": "amount.value",
      "message": "Debe ser un string decimal positivo."
    }
  ]
}
  }
}
```

## Catálogo

| Código                                       | HTTP | Retryable | Descripción                                                     |
| -------------------------------------------- | ---: | :-------: | --------------------------------------------------------------- |
| `invalid_request`                            |  400 |    No     | El request no cumple el contrato.                               |
| `invalid_credentials`                        |  401 |    No     | Email o contraseña incorrectos.                                 |
| `invalid_api_key`                            |  401 |    No     | API key inválida, expirada o revocada.                          |
| `invalid_refresh_token`                      |  401 |    No     | Refresh token inválido, expirado o revocado.                    |
| `unauthorized`                               |  401 |    No     | Falta autenticación de usuario.                                 |
| `insufficient_scope`                         |  403 |    No     | La API key no posee el scope requerido.                         |
| `insufficient_role`                          |  403 |    No     | El usuario no tiene el rol requerido.                           |
| `user_not_found`                             |  404 |    No     | El usuario no existe.                                           |
| `payment_method_not_found`                   |  404 |    No     | El método no existe o no está habilitado para la credencial.    |
| `idempotency_key_required`                   |  400 |    No     | Falta la clave de idempotencia.                                 |
| `idempotency_key_reused`                     |  409 |    No     | La clave fue usada con otro request.                            |
| `external_reference_conflict`                |  409 |    No     | Ya existe un pago con esa `external_reference` para la API key. |
| `unsupported_currency`                       |  422 |    No     | El método no soporta la moneda.                                 |
| `processor_declined`                         |  402 |    No     | El procesador rechazó la operación.                             |
| `processor_timeout`                          |  504 |    Sí     | No se obtuvo una respuesta concluyente.                         |
| `processor_unavailable`                      |  503 |    Sí     | El procesador no está disponible.                               |
| `connector_configuration_invalid`            |  500 |    No     | La configuración publicada del método no es ejecutable.         |
| `request_timeout`                            |  504 |    Sí     | La solicitud excedió el tiempo de espera.                       |
| `internal_error`                             |  500 |    Sí     | Error interno no esperado.                                      |

## Estrategia de manejo

1. Guardar `request_id`, endpoint, fecha UTC y referencia externa.
2. Si `retryable` es `false`, corregir credenciales, permisos, estado o payload antes de repetir.
3. Si `retryable` es `true` y es una escritura, repetir con la misma `Idempotency-Key` y el mismo body.
4. Aplicar backoff con límite; no crear una operación lógica nueva por un timeout.
5. Para pagos inciertos, consultar el recurso o esperar un webhook.

`processor_declined` es un rechazo concluyente. `processor_timeout`, `processor_unavailable`, `request_timeout` e `internal_error` pueden ser transitorios, pero `retryable: true` no garantiza éxito ni autoriza cambiar la clave de idempotencia.

Los errores `connector_configuration_invalid` son de configuración. Una aplicación de cobro debe escalarlos al administrador; no se corrigen cambiando el body del pago.

## Seguridad

No diferenciar públicamente:

- recurso inexistente;
- recurso de otro owner;
- recurso no habilitado para la API key.

Los tres casos usan el mismo error de recurso no encontrado.

Esta indistinguibilidad evita confirmar la existencia de recursos de otro owner.

Source: https://docs.pagofast.com/errors/index.mdx