Referencia de la API

Errores

Estructura de los errores, todos los códigos y cuándo volver a intentarlo.

Estructura#

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits.",
    "request_id": "a698a9af-0685-4557-9b29-ca57637748f9",
    "details": { "top_up_url": "https://scifig.ai/pricing?utm_source=api" }
  }
}

Decide el comportamiento según error.code y details.reason, nunca según message, que puede cambiar. Las respuestas nunca contienen diagnósticos internos.

Códigos#

Código	HTTP	Significado	Reintentar
UNAUTHORIZED	401	Faltan credenciales o no son válidas.	No; cambia la solicitud o usa una clave nueva
ACCOUNT_UNAVAILABLE	401	Esta cuenta no puede usar la API.	No; cambia la solicitud o usa una clave nueva
SCOPE_DENIED	403	Las credenciales no conceden este permiso.	No; cambia la solicitud o usa una clave nueva
INVALID_REQUEST	400	La solicitud no es válida.	No; cambia la solicitud o usa una clave nueva
IDEMPOTENCY_KEY_REQUIRED	400	Se requiere una cabecera Idempotency-Key de 1 a 255 caracteres ASCII visibles.	No; cambia la solicitud o usa una clave nueva
IDEMPOTENCY_CONFLICT	409	Este Idempotency-Key ya se ha usado con una solicitud diferente.	No; cambia la solicitud o usa una clave nueva
IDEMPOTENCY_IN_PROGRESS	409	Todavía se está procesando una solicitud con este Idempotency-Key.	Sí, con el mismo Idempotency-Key
NOT_FOUND	404	No se ha encontrado.	No; cambia la solicitud o usa una clave nueva
REVISION_CONFLICT	409	La tarea del gráfico o diagrama de flujo no se puede editar ahora: `NOT_LATEST_REVISION`, `EDIT_IN_PROGRESS` o `PARENT_JOB_RUNNING` mientras la tarea principal siga en ejecución.	Solo para `PARENT_JOB_RUNNING`: después de `Retry-After`, con la misma clave. En los demás casos, edita la versión más reciente con una clave nueva
PAYLOAD_TOO_LARGE	413	El cuerpo de la solicitud es demasiado grande.	No; cambia la solicitud o usa una clave nueva
INSUFFICIENT_CREDITS	402	No hay suficientes créditos.	No; cambia la solicitud o usa una clave nueva
CONTENT_REJECTED	422	La política de contenido ha rechazado la solicitud. Se devuelve como `422` al crear la solicitud o como `error.code` de una tarea fallida si ocurre durante la ejecución; los créditos se devuelven en ambos casos.	No; cambia la descripción o la entrada y usa una clave nueva
PLAN_REQUIRED	403	Tu plan no incluye esta opción.	No; cambia la solicitud o usa una clave nueva
RATE_LIMITED	429	Demasiadas solicitudes, tareas por hora, conversiones por día o subidas; `details.reason` indica la causa.	Sí, con el mismo Idempotency-Key
CONCURRENCY_LIMITED	429	Hay demasiadas tareas en ejecución para esta cuenta.	Sí, con el mismo Idempotency-Key
SERVICE_UNAVAILABLE	503	El servicio no está disponible temporalmente. Vuelve a intentarlo con el mismo Idempotency-Key.	Sí, con el mismo Idempotency-Key
TASK_FAILED	502	La tarea ha fallado y se han devuelto sus créditos. Envía una nueva solicitud con un nuevo Idempotency-Key para volver a intentarlo.	No; cambia la solicitud o usa una clave nueva
INTERNAL_ERROR	500	Error interno.	Sí, con el mismo Idempotency-Key

INVALID_REQUEST puede incluir details.reason, details.field o details.issues cuando esa información está disponible. Los cuerpos que superan el límite de 256 KB para JSON o los límites de archivo para subidas devuelven 413 PAYLOAD_TOO_LARGE. Solo INSUFFICIENT_CREDITS incluye details.top_up_url. Cuando una solicitud de creación falla después de crear la tarea (429, 503, 409 IDEMPOTENCY_IN_PROGRESS o 500 INTERNAL_ERROR), details.job_id identifica esa tarea: vuelve a intentarlo con el mismo Idempotency-Key o consulta GET /jobs/{job_id}, nunca con una clave nueva.

Códigos dentro de una tarea fallida#

Una tarea creada que después falla indica status: "failed" y un objeto error. Además de los códigos anteriores para solicitudes rechazadas, su error.code puede ser:

error.code	Significado	Qué hacer
TASK_TIMED_OUT	La tarea ha superado el tiempo límite y se han devuelto los créditos. La generación o edición de una ilustración puede incluir `late_delivery_until`: hasta ese momento el resultado puede llegar gratis.	Sigue consultando la tarea hasta `late_delivery_until`; en otro caso, envía una solicitud nueva con una clave nueva
CONTENT_REJECTED	La política de contenido ha rechazado el resultado durante la ejecución; se han devuelto los créditos. El mismo código se devuelve como `422` cuando se rechaza la propia solicitud al crearla.	Cambia la descripción o la entrada y usa una clave nueva
ADMISSION_INCOMPLETE	La tarea nunca se inició porque un error que permite reintentar lo impidió. No se consumieron créditos.	Envía la misma solicitud con el mismo Idempotency-Key
TASK_NOT_FOUND	La tarea se admitió, pero ya no se encuentra su ejecución.	Envía una solicitud nueva con una clave nueva
TASK_FAILED	La tarea ha fallado y se han devuelto los créditos. Cualquier error del motor sin código público propio pasa a ser `TASK_FAILED`; el código del motor está en `details.reason`.	Envía una solicitud nueva con una clave nueva
INTERNAL_ERROR	La tarea ha fallado sin indicar el motivo; se han devuelto los créditos.	Envía una solicitud nueva con una clave nueva

Causas de una respuesta 429#

Demasiadas solicitudes: 20 solicitudes de creación por minuto y credencial, 40 por cuenta y 120 lecturas por minuto y credencial. Retry-After indica el tiempo hasta que se reinicia la ventana; no hay details.reason.
Se han iniciado demasiadas tareas en la última hora: hasta 200 por cuenta, compartidas con el sitio web. Retry-After: 30.
Hay demasiadas tareas en ejecución: 429 CONCURRENCY_LIMITED, según el plan y compartidas con el sitio web; consulta GET /credits. Retry-After: 30.
Se ha agotado el cupo diario de 200 conversiones gratuitas a PNG, PDF, TIFF y PPTX: details.reason = DAILY_CONVERSION_LIMIT, con Retry-After hasta que se reinicia la ventana diaria.
Las subidas son demasiado rápidas: details.reason = UPLOAD_RATE_LIMITED para imágenes y máscaras en POST /files, archivos adjuntos de diagramas de flujo y datos de gráficos. Se aplica el límite de subidas por minuto del sitio web.
Demasiadas subidas en un día: details.reason = UPLOAD_DAILY_LIMIT_REACHED para archivos adjuntos de diagramas de flujo y datos de gráficos. Se aplica el límite diario de subidas del sitio web.
Detecciones de texto: 20 cada 15 minutos por cuenta, compartidas con el sitio web.

AnteriorCréditos SiguienteLímites de solicitudes y concurrenciaLímites de solicitudes, límites de tareas y cómo gestionar 429.