Documentación de la API de Fileverity

Errores

El formato de errores de la API de Fileverity, los estados HTTP y la tabla completa de códigos de error, con indicaciones sobre qué errores reintentar.

Ver como MarkdownActualizado el 2026-11-04

Los errores usan un estado HTTP estándar y un cuerpo JSON con un code estable. Base su lógica en code, no en message: los mensajes pueden cambiar.

{  "error": {    "type": "invalid_request_error",    "code": "invalid_parameter",    "message": "Unrecognized parameter: files.",    "param": "files",    "request_id": "req_4mQ9cX2vB7nP1sK8tL3wR6yZ"  }}

Campo	Descripción
`error.type`	La categoría. Cada tipo corresponde a una familia de estados HTTP, que se enumeran más abajo.
`error.code`	Un identificador estable y legible por máquinas.
`error.message`	Una explicación legible por personas. Puede nombrar el campo o el límite implicado.
`error.param`	El campo de la solicitud que causó el error, o `null`.
`error.request_id`	El ID de esta solicitud, que también está en el encabezado de respuesta `x-request-id`. Indíquelo cuando contacte con soporte en hello@fileverity.com.

Tipos de error

Tipo	Estado	Significado
`invalid_request_error`	400, 413, 415, 422	La solicitud está mal formada o supera un límite. Corrija la solicitud; si se reintenta sin cambios, vuelve a fallar.
`authentication_error`	401	Falta la clave de API o no es válida.
`billing_error`	402	El saldo o un límite de gasto impide la solicitud. Añada fondos o aumente el límite.
`not_found_error`	404	El recurso no existe, ha caducado o pertenece a otro espacio de trabajo.
`conflict_error`	409	La solicitud entra en conflicto con el estado actual.
`rate_limit_error`	429	Demasiadas solicitudes o demasiadas subidas pendientes. Con `rate_limited`, espere los segundos de `retry-after`. `pending_files_limit` no incluye `retry-after`: use los archivos, elimínelos o espere a que caduquen.
`api_error`	500, 502, 503	Un problema por nuestra parte o capacidad ocupada. Estas solicitudes no se cobraron. Reintente con retroceso exponencial. `service_unavailable` incluye un encabezado `retry-after`.

Qué reintentar

Reintente rate_limited tras los segundos de retry-after, e internal_error, analysis_failed y service_unavailable con retroceso exponencial (con service_unavailable, empiece con los segundos de retry-after). Envíe la misma Idempotency-Key para que un reintento no pueda ejecutarse dos veces. Consulte Idempotencia.
Reintente tras esperar idempotency_in_progress.
No reintente los demás errores 4xx hasta que cambie la solicitud o el estado de la cuenta.
Una comprobación que termina en error no se cobra.

¿Sigue sin resolverlo? Escriba a hello@fileverity.com o use la página de contacto, e incluya el ID de solicitud.

Códigos de error

Esta tabla se genera a partir de las propias definiciones de error de la API.

Código	Estado	Tipo	Mensaje
`invalid_json`	400	`invalid_request_error`	El cuerpo de la solicitud debe ser un objeto JSON.
`missing_parameter`	400	`invalid_request_error`	Falta un parámetro obligatorio.
`invalid_parameter`	400	`invalid_request_error`	Un parámetro tiene un valor no válido.
`text_too_short`	400	`invalid_request_error`	El texto es demasiado corto para evaluarlo. Envíe al menos 100 palabras.
`text_too_long`	413	`invalid_request_error`	El texto supera los 100 000 caracteres. Divídalo en varias solicitudes.
`unsupported_media_type`	415	`invalid_request_error`	Envíe el cuerpo de la solicitud como JSON con el encabezado "Content-Type: application/json".
`unsupported_language`	400	`invalid_request_error`	El texto no está en un idioma admitido. Los idiomas admitidos son en, fr, de, es y zh.
`file_not_found`	400	`invalid_request_error`	No se encontró el archivo subido o este ha caducado. Súbalo de nuevo.
`unsupported_file`	415	`invalid_request_error`	El formato del archivo no se admite en este modelo.
`file_too_large`	413	`invalid_request_error`	El archivo supera el límite de tamaño de este modelo.
`too_many_pixels`	413	`invalid_request_error`	La imagen supera los 40 megapíxeles.
`too_many_pages`	413	`invalid_request_error`	El documento supera las 100 páginas.
`document_too_long`	413	`invalid_request_error`	El documento contiene demasiado texto para analizarlo en una sola solicitud.
`invalid_file`	422	`invalid_request_error`	El archivo está dañado o no se puede leer.
`password_required`	422	`invalid_request_error`	El documento está cifrado. Envíe su contraseña para analizarlo.
`wrong_password`	422	`invalid_request_error`	La contraseña del documento es incorrecta.
`not_examinable`	422	`invalid_request_error`	El documento no tiene texto, fotos ni estructura que se puedan examinar. No se le ha cobrado.
`missing_api_key`	401	`authentication_error`	No se proporcionó ninguna clave de API. Envíela en el encabezado "Authorization: Bearer fv_live_...".
`invalid_api_key`	401	`authentication_error`	La clave de API no es válida o se ha revocado.
`insufficient_balance`	402	`billing_error`	Su saldo es insuficiente para esta solicitud. Añada fondos en la Consola.
`spend_limit_reached`	402	`billing_error`	Esta clave de API ha alcanzado su límite de gasto mensual. Aumente el límite en la Consola o espere al mes siguiente (UTC).
`not_found`	404	`not_found_error`	El recurso solicitado no existe.
`model_not_found`	404	`not_found_error`	El modelo no existe o no está disponible.
`not_cancelable`	409	`conflict_error`	El análisis ya no se puede cancelar.
`canceled`	409	`conflict_error`	El análisis se canceló. No se le ha cobrado.
`idempotency_mismatch`	409	`conflict_error`	Esta Idempotency-Key ya se usó con un cuerpo de solicitud distinto.
`idempotency_in_progress`	409	`conflict_error`	Una solicitud con esta Idempotency-Key todavía se está procesando. Vuelva a intentarlo en breve.
`pending_files_limit`	429	`rate_limit_error`	Este espacio de trabajo tiene demasiadas subidas pendientes. Analice o elimine los archivos subidos, o espere hasta 24 horas a que caduquen.
`rate_limited`	429	`rate_limit_error`	Demasiadas solicitudes. Reintente tras el número de segundos que indica el encabezado Retry-After.
`internal_error`	500	`api_error`	No se pudo completar la solicitud. Vuelva a intentarla; si el problema persiste, contacte con soporte e indique el ID de solicitud.
`analysis_failed`	502	`api_error`	No se pudo completar el análisis. No se le ha cobrado; vuelva a intentarlo y, si falla de nuevo, contacte con soporte e indique el ID de solicitud.
`service_unavailable`	503	`api_error`	El servicio no está disponible temporalmente o está ocupado. No se le ha cobrado; reintente tras el número de segundos que indica el encabezado Retry-After.

Códigos exclusivos de la Consola

Estos códigos los devuelven los endpoints propios de la Consola, que funcionan con su sesión iniciada. Las solicitudes realizadas con una clave de API no los devuelven.

Código	Estado	Tipo	Mensaje
`session_required`	401	`authentication_error`	Inicie sesión para continuar.
`forbidden`	403	`permission_error`	No tiene permiso para hacer esto.
`invite_invalid`	404	`not_found_error`	Esta invitación no es válida, ha caducado o ya se usó.
`invite_mismatch`	403	`permission_error`	Esta invitación se envió a otra dirección de correo electrónico.
`invite_limit`	409	`conflict_error`	Este espacio de trabajo ya tiene el número máximo de invitaciones pendientes. Revoque primero una.
`last_owner`	409	`conflict_error`	Un espacio de trabajo debe conservar al menos un propietario. Nombre primero a otro miembro como propietario.
`webhook_limit`	409	`conflict_error`	Este espacio de trabajo ya tiene el número máximo de endpoints de webhook. Elimine primero uno.
`key_limit`	409	`conflict_error`	Este espacio de trabajo ya tiene el número máximo de claves de API activas. Revoque primero una.

Errores

Tipos de error#

Qué reintentar#

Códigos de error#

Códigos exclusivos de la Consola#

Tipos de error

Qué reintentar

Códigos de error

Códigos exclusivos de la Consola