OAuth 2.1

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ódigoHTTPEndpoint(s)CausaResolución
invalid_request400TodosParámetro faltante, duplicado o malformadoRevisa los parámetros requeridos del endpoint
unauthorized_client401/authorize, /tokenEl cliente no tiene permiso para el grant type solicitadoVerifica que el grant_type esté en los grant_types registrados
access_denied302 / HTML/authorizeEl usuario rechazó el consentimientoMuestra un mensaje apropiado al usuario
unsupported_response_type400/authorizeresponse_type distinto de codeUsa response_type=code
invalid_scope400/authorize, /tokenScope desconocido o que excede los concedidosVerifica la tabla de scopes
server_error500TodosError interno en WhataloReintenta con backoff exponencial
temporarily_unavailable503TodosMantenimiento o sobrecarga temporalReintenta después del Retry-After indicado
invalid_client401/token, /introspect, /revokeclient_secret incorrecto o faltanteVerifica las credenciales del cliente
invalid_grant400/tokenCódigo expirado, ya usado, o code_verifier PKCE incorrectoReinicia el flujo de autorización
invalid_redirect_uri400/authorizeredirect_uri no registrada para el clienteRegistra la URI exacta via DCR
invalid_target400/authorize, /tokenParámetro resource (RFC 8707) inválido o no permitidoVerifica el valor del parámetro resource
rate_limit_exceeded429/token, /registerLímite de solicitudes superadoEspera 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_ORIGINAL

Errores 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

EndpointLímite
POST /oauth/token60 req/min por IP + 30 req/min por client_id
POST /oauth/register10 req/hora por IP
POST /oauth/introspectIncluido en el límite general de la API
POST /oauth/revokeIncluido en el límite general de la API

Para los límites de la API REST general, ver Límites de tasa.

On this page