> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recurrente.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recurrente.com/_mcp/server.

# Errores

> Manejo de errores en la API de Recurrente

La API usa códigos de estado HTTP estándar y retorna cuerpos de error en JSON.

## Códigos de Estado HTTP

| Código | Significado                                                                                        |
| ------ | -------------------------------------------------------------------------------------------------- |
| `200`  | Éxito                                                                                              |
| `201`  | Creado                                                                                             |
| `400`  | Solicitud Incorrecta — parámetros inválidos                                                        |
| `401`  | No Autorizado — llaves de API inválidas o faltantes                                                |
| `422`  | No Procesable — solicitud entendida pero no se puede completar                                     |
| `429`  | Demasiadas Solicitudes — excediste un límite de tasa; espera los segundos del header `Retry-After` |
| `500`  | Error del Servidor                                                                                 |

## Formato de Respuesta de Error

La API retorna errores en el siguiente formato:

```json
{
  "message": "Checkout Inválido",
  "errors": {
    "items": ["can't be blank"]
  }
}
```

El campo `message` siempre está presente. El objeto `errors` es opcional y contiene detalles de validación a nivel de campo.

## Errores Comunes

### Autenticación Fallida

```json
// 401
{
  "message": "Autenticación Errónea 👀",
  "errors": {
    "authentication": [
      "Las llaves de API son inválidas o no coinciden."
    ]
  }
}
```

Tus llaves de API son inválidas, faltan, o no coinciden con la misma cuenta/ambiente.

Si envías una llave `sk_test_` que ya no existe, el mensaje en `errors.authentication` es:
"Esta llave TEST no existe. Las cuentas LIVE ya no tienen llave TEST: las llaves TEST ahora viven en un Sandbox. Ábrelo en Configuración → Llaves API → Sandbox y usa su llave TEST." Las cuentas de producción ya no tienen llave TEST; crea una dentro de un Sandbox.

Una llave cuyo ambiente no coincide con el de su cuenta responde `401` con `"code": "environment_mismatch"`.

### Error de Validación

```json
// 400
{
  "message": "Producto Inválido",
  "errors": { "name": ["can't be blank"] }
}
```

Los parámetros proporcionados no pasan la validación. Revisa el objeto `errors` para detalles específicos.

### No Se Puede Modificar Checkout Pagado

```json
// 422
{ "message": "No se puede modificar un checkout pagado" }
```

Intentaste modificar un checkout que ya ha sido pagado.

### Recurso No Encontrado

```json
// 404
{ "message": "Producto no encontrado" }
```

El recurso solicitado no existe o no pertenece a tu cuenta.

## Límites de Tasa

Cada llave secreta tiene un presupuesto de ráfaga de 60 solicitudes por segundo, independiente de la dirección IP desde la que llamas. Solo en `/api/users` aplica además un límite de 300 solicitudes cada 5 minutos por dirección IP, y las llaves `sk_test_` tienen un tope adicional de 300 solicitudes cada 5 minutos por llave en esa ruta. Las variantes de formato, como `/api/users.json`, comparten esos presupuestos. Los demás endpoints, incluidos `/api/checkouts`, `/api/products` y `/api/customers`, conservan el límite de ráfaga de 60 solicitudes por segundo por llave, sin esos topes de cinco minutos.

Al exceder un límite la API responde `429` con el header `Retry-After` en segundos. Espera ese tiempo antes de reintentar y usa espera exponencial si el `429` se repite.

```http
HTTP/2 429 Too Many Requests
Retry-After: 1
```

Un `503` con cuerpo `Blocked` no es este throttle: corresponde a una regla de bloqueo de seguridad y no se resuelve esperando el `Retry-After`. Comparte con soporte la hora y el identificador de la petición para identificar la regla.

## Manejo de Errores

Siempre verifica el código de estado HTTP antes de procesar la respuesta:

```javascript
if (response.status >= 400) {
  const error = await response.json();
  console.error('Error de API:', error.message);
  
  // Manejar errores de validación específicos
  if (error.errors) {
    Object.keys(error.errors).forEach(field => {
      console.error(`${field}: ${error.errors[field].join(', ')}`);
    });
  }
}
```

## Diagnosticar tu Sandbox

Antes de probar un ID, llama `GET /test` con la misma llave y confirma `environment: sandbox`. Un ID de otra cuenta o ambiente no se puede reutilizar. `sandbox_unsupported` indica una operación bloqueada. Una llave enmascarada no autentica: crea una llave nueva o rota la anterior si deseas revocarla. Consulta [el diagnóstico de primer pago](/guias-espanol/comenzar/primer-pago-de-prueba#si-algo-no-funciona).