Errores, paginación e idempotencia
Respuestas estándar, límites, reintentos y diagnóstico seguro.
Formato estándar
{
"error": {
"code": "validation_error",
"message": "La solicitud contiene datos inválidos.",
"request_id": "f0d7...",
"details": {"form_id": ["..."]}
}
}| HTTP | Código | Qué hacer |
|---|---|---|
| 400 | idempotency_key_required | Agrega una clave estable para esa operación. |
| 401 | unauthorized, token_expired, token_revoked | Revisa o rota el token. |
| 403 | insufficient_scope, ip_not_allowed | Corrige permisos o IP desde Administración. |
| 404 | resource_not_found | Verifica el ID público y la cuenta de la URL. |
| 409 | idempotency_conflict | No reutilices una clave con contenido diferente. |
| 422 | validation_error, invalid_destination, plan_limit_exceeded | Corrige datos, destino o capacidad del plan. |
| 429 | rate_limit_exceeded | Espera Retry-After y usa backoff con jitter. |
Reintentos seguros
Reintenta solo errores de red, 429 y 5xx, usando espera exponencial con variación. En creaciones conserva la misma Idempotency-Key. No reintentes automáticamente errores 4xx distintos de 429.
Paginación
{
"data": [],
"meta": {"page": 1, "per_page": 50, "last_page": 4, "total": 184},
"request_id": "f0d7..."
}Soporte
Comparte el request_id, fecha aproximada, endpoint y estado HTTP. Nunca envíes el token completo ni datos personales en un ticket.