Errores OAuth
Códigos de error OAuth 2.1 de Whatalo, su significado y cómo resolverlos.
Los errores OAuth de Whatalo siguen los estándares RFC 6749 §4.1.2.1, RFC 6749 §5.2 y RFC 7009. El formato y el canal de entrega del error dependen de en qué endpoint ocurre.
Formato de error
Los endpoints de token, introspección y revocación devuelven siempre JSON:
{
"error": "invalid_grant",
"error_description": "Authorization code has expired or was already used"
}Tabla de códigos de error
| Código | HTTP | Endpoint(s) | Causa | Resolución |
|---|---|---|---|---|
invalid_request | 400 | Todos | Parámetro faltante, duplicado o malformado | Revisa los parámetros requeridos del endpoint |
unauthorized_client | 401 | /authorize, /token | El cliente no tiene permiso para el grant type solicitado | Verifica que el grant_type esté en los grant_types registrados |
access_denied | 302 / HTML | /authorize | El usuario rechazó el consentimiento | Muestra un mensaje apropiado al usuario |
unsupported_response_type | 400 | /authorize | response_type distinto de code | Usa response_type=code |
invalid_scope | 400 | /authorize, /token | Scope desconocido o que excede los concedidos | Verifica la tabla de scopes |
server_error | 500 | Todos | Error interno en Whatalo | Reintenta con backoff exponencial |
temporarily_unavailable | 503 | Todos | Mantenimiento o sobrecarga temporal | Reintenta después del Retry-After indicado |
invalid_client | 401 | /token, /introspect, /revoke | client_secret incorrecto o faltante | Verifica las credenciales del cliente |
invalid_grant | 400 | /token | Código expirado, ya usado, o code_verifier PKCE incorrecto | Reinicia el flujo de autorización |
invalid_redirect_uri | 400 | /authorize | redirect_uri no registrada para el cliente | Registra la URI exacta via DCR |
invalid_target | 400 | /authorize, /token | Parámetro resource (RFC 8707) inválido o no permitido | Verifica el valor del parámetro resource |
rate_limit_exceeded | 429 | /token, /register | Límite de solicitudes superado | Espera el tiempo indicado en Retry-After |
Enrutamiento de errores
El canal por el que recibes el error depende de si Whatalo puede validar el client_id y redirect_uri:
Errores redirigibles (flujo de autorización)
Cuando el client_id y el redirect_uri son válidos y conocidos, Whatalo redirige el error de vuelta a tu app:
https://mi-app.com/oauth/callback?
error=access_denied
&error_description=El+usuario+canceló+el+consentimiento
&state=VALOR_STATE_ORIGINALErrores que se redirigen: access_denied, invalid_scope, unsupported_response_type, server_error, temporarily_unavailable.
Errores no redirigibles
Cuando Whatalo no puede verificar el client_id o la redirect_uri (porque son inválidos o desconocidos), no puede redirigir — hacerlo podría ser un vector de ataque. En ese caso, Whatalo muestra una página de error con marca propia en /oauth/error.
Errores que muestran página propia: invalid_client, invalid_redirect_uri.
Errores de token endpoint
Los endpoints /oauth/token, /oauth/introspect y /oauth/revoke devuelven siempre JSON — nunca HTML ni redirecciones.
Manejo recomendado
Backoff exponencial para 429 y 503
async function callWithRetry(fn, maxAttempts = 4) {
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
return await fn();
} catch (err) {
if (err.status !== 429 && err.status !== 503) throw err;
const retryAfter = err.headers?.get("Retry-After");
const waitMs = retryAfter
? Number(retryAfter) * 1000
: Math.pow(2, attempt) * 500;
await new Promise((r) => setTimeout(r, waitMs));
}
}
throw new Error("Max retry attempts exceeded");
}Manejo de invalid_grant
invalid_grant en el token endpoint significa que el flujo de autorización debe reiniciarse:
async function refreshAccessToken(refreshToken) {
const res = await fetch("https://app.whatalo.com/oauth/token", { ... });
const data = await res.json();
if (data.error === "invalid_grant") {
// Token family revoked — user must re-authorize
clearStoredTokens();
redirectToAuthorizationFlow();
return;
}
if (!res.ok) throw new Error(data.error_description);
return data;
}Límites de tasa por endpoint OAuth
| Endpoint | Límite |
|---|---|
POST /oauth/token | 60 req/min por IP + 30 req/min por client_id |
POST /oauth/register | 10 req/hora por IP |
POST /oauth/introspect | Incluido en el límite general de la API |
POST /oauth/revoke | Incluido en el límite general de la API |
Para los límites de la API REST general, ver Límites de tasa.