# Errores

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

Fuente: https://scifig.ai/es/docs/api/errors

## Estructura

```json
{
  "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.