Errores de la API
Cada respuesta de error lleva un code estable y un docs_url que trae al ancla de ese código en esta página, en tu idioma. El message va en inglés, para máquinas; lo de aquí es para personas. Cítanos el request_id si algo no cuadra.
Errores de la petición
Lo que responde la API cuando la petición no sale adelante.
invalid_api_key
La key falta, no existe o está revocada. Va en X-Api-Key o en Authorization: Bearer; si llegan las dos, manda la primera.
invalid_token
El ID token de la persona falta, está caducado o no verifica. Solo afecta a /admin, que es para personas y no para keys.
impersonation_ended
El token de X-Lince-Impersonation ya no vale: caducó (duran 60 minutos), se terminó, otra impersonación de la misma persona ocupó su lugar o es de otra persona. Solo le llega al equipo de Spock, desde /api/admin; inicia otra impersonación desde la consola interna.
account_suspended
La cuenta está suspendida. Se sigue pudiendo consultar lo que ya hay; no se admiten lecturas nuevas.
payment_required
La suscripción no está activa o el periodo de prueba ha terminado, así que las keys live no se admiten. Las test siguen funcionando. Distinto de insufficient_credit: aquello es quedarse sin lecturas del trial o sin saldo; esto es que la suscripción no da derecho a leer.
insufficient_scope
La API key no tiene el alcance que pide esta llamada: read para las llamadas GET, write para crear lecturas y enviar feedback, delete para borrar una lectura. No se ha hecho nada. Los alcances de una key se eligen al crearla en la consola; para cambiarlos, crea otra key.
forbidden_role
Tu rol en la cuenta no permite esta acción.
admin_role_required
Solo un administrador de la consola interna puede hacer cambios; quien solo consulta, únicamente puede mirar.
second_factor_required
Esta zona exige la verificación en dos pasos: actívala en la consola y vuelve a entrar con el código de tu app de autenticación.
recent_sign_in_required
Esta acción exige haber entrado en los últimos 15 minutos: vuelve a entrar y repítela.
no_account
La identidad es válida pero no es miembro de ninguna cuenta. El vínculo se hace en el primer acceso con el correo verificado.
insufficient_credit
No hay saldo para pagar la lectura. Afecta solo al modo live.
concurrency_exceeded
Demasiadas lecturas en curso a la vez para esta cuenta. Es el límite que protege el coste real: espera a que terminen y reintenta.
quota_exceeded
Se agotaron las lecturas contratadas del mes.
daily_limit_exceeded
Se alcanzó el tope de gasto diario de la cuenta. Se reinicia a medianoche, hora peninsular.
rate_limit_exceeded
Demasiadas peticiones por minuto. La respuesta trae Retry-After y las cabeceras X-RateLimit-*.
api_key_limit_reached
La cuenta ya tiene el máximo de keys activas. Revoca una antes de crear otra.
member_limit_reached
La cuenta ya tiene el máximo de personas con acceso a /admin.
account_name_taken
Ya hay una cuenta con ese nombre. Elige otro; param es account_name.
email_not_allowed
Con ese correo no se puede crear una cuenta: es de un dominio desechable o ya pertenece a otra identidad. El mensaje es genérico a propósito y no dice cuál de las dos.
email_not_verified
El correo de la identidad todavía no está verificado, y el alta exige verificarlo. Solo lo devuelve POST /console/signup. No es no_account: aquello es no ser miembro de ninguna cuenta, y aquí basta con abrir el enlace que mandamos y repetir la llamada. Ojo con el ID token en caché: el claim email_verified no cambia hasta que se pide uno nuevo.
last_owner
La operación dejaría la cuenta sin ningún owner. Nombra otro antes de degradar o retirar el último.
subscription_exists
La cuenta ya tiene una suscripción de Stripe activa: para cambiar de plan es POST /api/admin/billing/plan, y para la tarjeta o cancelar, el Portal. Solo lo devuelve POST /api/admin/billing/checkout.
no_subscription
No hay una suscripción de Stripe con la que hacer eso. Lo normal es que la cuenta todavía no haya contratado: antes hay que pasar por POST /api/admin/billing/checkout. También sale en el cambio de plan cuando la suscripción de Stripe no tiene la forma de un plan nuestro o no se pudo sincronizar después del cambio; en ese caso escríbenos. Lo devuelven el Portal y el cambio de plan.
plan_not_billable
Ese plan no se contrata en línea (no es público), o es el que la cuenta ya tiene. param es plan.
idempotency_key_reused
La misma Idempotency-Key se usó con un cuerpo distinto. Reutilizarla con el mismo cuerpo devuelve la lectura original; con otro es un error.
reading_not_completed
Solo se puede dar feedback a una lectura completed.
reading_not_settled
La lectura aún no se puede borrar: se está leyendo todavía, o lo que cuesta no se ha liquidado. Vuelve a intentarlo en unos minutos; no se ha borrado nada.
review_already_resolved
Esa revisión ya la resolvió alguien. La resolución dice quién y cuándo.
export_not_ready
La exportación aún se está generando, o ha fallado. Consulta GET /api/admin/exports/{id} hasta que su status sea ready; una failed hay que volver a pedirla.
not_impersonating
DELETE /api/admin/impersonation llegó sin la cabecera X-Lince-Impersonation, así que no había ninguna impersonación que terminar. No se ha hecho nada.
access_request_closed
La solicitud de acceso ya está registrada o descartada, así que ya no se puede invitar ni descartar. No se ha hecho nada.
invitations_disabled
Las invitaciones están desactivadas en este entorno, así que el enlace no funcionaría. No se ha enviado nada.
email_already_member
El email de la solicitud de acceso ya es miembro de una cuenta: añade a la persona desde esa cuenta. No se ha enviado nada.
export_expired
El fichero de la exportación ya no está: se conservan 24 horas desde que están listas. Pídela de nuevo.
validation_failed
El cuerpo o los parámetros no cumplen el contrato. param dice cuál.
payload_too_large
La petición entera supera el tope de tamaño del servicio, que es fijo e igual para todas las cuentas. No es el límite de tu perfil: un fichero que pasa del tamaño por fichero de tu perfil se admite como lectura failed con file_too_large, y pasarse del número de ficheros por petición es validation_failed.
malformed_request
La petición no se pudo interpretar: JSON roto, multipart mal formado o cabeceras incoherentes.
method_not_allowed
El método no existe en esa ruta. La respuesta trae Allow.
resource_not_found
No hay tal recurso, o no es de tu cuenta. Las dos cosas responden igual a propósito: no se revela de quién es cada id.
http_error
Un error HTTP sin código propio. Conserva el status original en vez de disfrazarse de 500.
internal_error
Algo se rompió por nuestra parte. Lleva request_id: cítalo si escribes a soporte.
De una lectura fallida
Estos no llegan como error HTTP: la petición se aceptó y fue la lectura la que falló. Van en Reading.error.code, y el type es siempre processing.
unsupported_file_type
El fichero no es un PDF. Es el único formato que se admite, y se reconoce por su contenido, no por el nombre ni por la extensión.
file_too_large
El fichero supera el tamaño por fichero del perfil de la cuenta.
too_many_pages
El documento tiene más páginas de las que el perfil admite leer.
unreadable_document
No hay una factura que leer: o el PDF está dañado y no se pudo abrir, o se abrió y dentro no hay una factura legible.
engine_error
El motor lo intentó y falló. Es nuestro, no tuyo.
never_started
Ningún worker llegó a procesarla: esperó en la cola demasiado tiempo y se dio por fallida antes de empezar. Es capacidad, no el motor.