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 " ,
"code" : " WORK_REVISION_CONFLICT " ,
"detail" : " The work changed since that revision. Read it again before publishing. " ,
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.