Errores y reintentos
Los errores de API utilizan un formato consistente. El código es para la lógica de la aplicación; el mensaje explica el problema. Mantenga la entrada del usuario intacta y ofrezca un siguiente paso claro.
En esta página
Un solo formato de error#
Las respuestas no incluyen trazas de pila, SQL, tokens ni una respuesta completa del proveedor externo. No muestre registros internos sin procesar a un cliente.
{
"error": {
"code": "GATEWAY_NOT_CONNECTED",
"message": "Financial operations are temporarily unavailable. Try later or contact support."
}
}Grupos de errores comunes#
| HTTP | Ejemplos | Siguiente paso |
|---|---|---|
| 400 | INVALID_JSON, UNKNOWN_FIELD, INVALID_INPUT | Verifique la entrada y los campos permitidos |
| 401 | AUTH_REQUIRED, SESSION_EXPIRED | Inicie sesión nuevamente |
| 403 | INVALID_ORIGIN, CSRF_REQUIRED | Verifique el origin y la sesión actual |
| 404 | NOT_FOUND, TICKET_NOT_FOUND | Verifique la dirección y la propiedad |
| 409 | CHALLENGE_UNAVAILABLE | Inicie un nuevo inicio de sesión |
| 410 | CHALLENGE_EXPIRED | Cree un nuevo enlace de inicio de sesión |
| 413 | REQUEST_TOO_LARGE | Reduzca el cuerpo de la solicitud |
| 415 | JSON_REQUIRED | Envíe application/json |
| 429 | RATE_LIMITED | Reduzca la frecuencia y espere |
| 503 | GATEWAY_NOT_CONNECTED, SERVICE_UNAVAILABLE | Verifique la disponibilidad o intente más tarde |
Límites de velocidad#
| Acción | Límite |
|---|---|
| Iniciar sesión | 6 por minuto por dirección con hash |
| Verificar un desafío | 90 por minuto por desafío |
| Pregunta de conocimiento | 12 por minuto por dirección con hash con D1 |
| Crear un enlace de servidor | 20 por minuto por usuario |
| API de comerciante | 90 solicitudes por minuto por clave |
| Nueva aplicación | Cinco por día por usuario |
| Reanudar aplicación / decisión del moderador | 30 por minuto por usuario para cada acción |
| Revisión de sitio web con IA | 30 por hora en todo el servicio |
| Leer el pago o intentar el pago | 90 por minuto por dirección hashada |
| Crear una solicitud de soporte | 6 por hora por usuario |
| Probar una notificación | 3 por hora por usuario |
| Generación con IA | 60 por hora en todo el servicio por defecto |
Qué se puede reintentar#
Una lectura se puede reintentar después de una demora ante una falla temporal de red. Antes de reintentar una mutación, verifique si la original se completó; una respuesta perdida no demuestra una falla.
Las operaciones financieras requieren idempotencia y una verificación del estado del servidor. Una redirección del cliente a una página de resultados no sustituye la confirmación.
Qué incluir en una solicitud#
- La página y la acción inmediatamente antes del error.
- Hora, zona horaria y el código de error visible.
- Su referencia de factura o de solicitud de soporte, si está disponible.
- Una descripción breve del resultado que esperaba.