Ir al contenido

Errores

En /connect y /oauth/authorize, los errores siguen RFC 9457 con Content-Type: application/problem+json:

{
"type": "https://api.lectoresbeta.com/problems/work-revision-conflict",
"title": "Conflict",
"status": 409,
"code": "WORK_REVISION_CONFLICT",
"detail": "The work changed since that revision. Read it again before publishing.",
"currentRevision": 7
}
  • Decide siempre por code, que es estable. detail es para personas, está en inglés y puede cambiar.
  • Algunos errores llevan campos extra, como currentRevision.
  • Los errores de validación (422 VALIDATION_FAILED) traen además errors, con un field y un code por campo.

En /oauth/token y /oauth/revoke, los errores siguen RFC 6749 §5.2, que es lo que esperan las bibliotecas OAuth:

{ "error": "invalid_grant", "error_description": "The grant is invalid, expired or revoked." }
Respuesta code / cabecera Significa Qué hacer
401 UNAUTHENTICATED, WWW-Authenticate: Bearer No se envió token Envía Authorization: Bearer …
401 INVALID_ACCESS_TOKEN, WWW-Authenticate: Bearer error="invalid_token" Token caducado, revocado o ya sin autorización detrás Renueva una vez; si falla, vuelve a pedir autorización
403 INSUFFICIENT_SCOPE, WWW-Authenticate: … scope="…" El token no tiene el permiso de esa operación Pide autorización incluyendo ese permiso
403 ACCOUNT_NOT_ACTIVATED La cuenta no está activada y la operación escribe Pide a la persona que active su cuenta
429 TOO_MANY_REQUESTS, Retry-After Demasiadas peticiones a /oauth Espera los segundos que indica Retry-After
Dónde Error Cuándo
En el navegador, sin redirigir (422) INVALID_CONNECTED_APP_CLIENT client_id desconocido o aplicación desactivada
En el navegador, sin redirigir (422) INVALID_REDIRECT_URI La redirect_uri no es una de las registradas
De vuelta en tu redirect_uri unsupported_response_type response_type no es code
De vuelta en tu redirect_uri invalid_request Falta state, o PKCE falta, no es S256 o el reto no es válido
De vuelta en tu redirect_uri invalid_scope Permiso desconocido, ninguno, o no permitido a tu aplicación
De vuelta en tu redirect_uri access_denied La persona canceló
HTTP error Cuándo Qué hacer
400 invalid_request Falta un parámetro, o el cuerpo no va como formulario Revisa el Content-Type y los campos
400 unsupported_grant_type grant_type no es authorization_code ni refresh_token
400 invalid_grant Código o refresco desconocido, caducado o ya usado; client_id, redirect_uri o code_verifier que no cuadran; autorización retirada o aplicación desactivada Vuelve a pedir autorización desde el principio
400 invalid_scope Al renovar, scope pide más de lo concedido Pide solo lo concedido o menos

invalid_grant no dice cuál de las comprobaciones falló, a propósito.

HTTP code Cuándo
404 WORK_NOT_FOUND La obra no existe o no es de la persona (se responde igual)
409 WORK_REVISION_CONFLICT La obra cambió desde baseRevision. Lleva currentRevision
409 ILLEGAL_WORK_TRANSITION Pedir correcciones de una obra en borrador sin publishIfDraft
409 CHAPTER_HAS_CORRECTIONS Quitar un capítulo que ya tiene correcciones
409 CHAPTER_BLOCKED Cambiar o quitar un capítulo bloqueado por moderación
409 SINGLE_TEXT_HAS_ONE_CHAPTER Más de un capítulo en un texto corto
409 WORK_NEEDS_A_CHAPTER Dejar sin capítulos una obra publicada
422 CHAPTER_OMITTED Un capítulo existente no está ni en chapters ni en removedChapterIds
422 CHAPTER_NOT_IN_WORK Un chapterId no es de esta obra
422 CHAPTER_LISTED_TWICE Un capítulo repetido, o a la vez editado y quitado
422 EMPTY_CHAPTER Un capítulo sin texto después de sanear el HTML
422 UNKNOWN_GENRE / TOO_MANY_GENRES Temática que no existe, o más de tres
422 INVALID_VALUE Un campo vacío, demasiado largo o con un formato inválido
HTTP code Cuándo
404 CORRECTION_NOT_FOUND No existe o no es una corrección recibida por la persona
409 CORRECTION_LOCKED Pedir el texto de una corrección retenida por saldo negativo

Un 5xx es un fallo nuestro: no es culpa de la petición. Reintenta más tarde con espera creciente, y no reintentes automáticamente una escritura (POST) sin comprobar antes su efecto: por ejemplo, vuelve a leer la obra y mira su revision antes de publicar otra vez una versión.

Última actualización: