Errores

El Reigniter API utiliza códigos estándar HTTP estado. Cada respuesta de error es JSON.

Cuerpo de error

La mayoría de los errores se ven así:

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "retryAfter": 37
}

Campo	Siempre presente	Qué es
`error`	Sí	Un mensaje que puedes mostrar a una persona. Puede cambiar la redacción, así que no coincidas con él.
`code`	Más errores	Un código estable en mayúsculas. Haz una rama en esto.
`details`	Algunos errores	Contexto extra, por ejemplo `retryAfter` o cifras de uso.
`retryAfter`	Algunas `429`s	Segundos para esperar antes de intentarlo de nuevo.

Algunos errores no tienen code, como 404 Job not found y 403 Forbidden. Branch en el estado para esos.

Errores de validación

Cuando el cuerpo de la solicitud no coincide con el esquema, obtienes 400 con una cadena de detail que lista cada problema como field: message:

{
  "error": "Validation failed",
  "detail": "aspect: Invalid option: expected one of \"9:16\"|\"16:9\"|\"1:1\"|\"4:5\"|\"4:3\"|\"3:4\""
}

Códigos de estado

Estado	Significado	Qué hacer
`200`	Éxito.
`201`	Creada (webhooks).
`202`	Aceptado. El renderizado ha comenzado.	Consulta el trabajo o espera el webhook.
`400`	La solicitud fue rechazada. No se cobró nada.	Arregla la petición. No lo intentes sin cambios.
`401`	Falta una clave, es inválida o revocada API.	Mira la llave.
`402`	Problema de planificación, crédito o uso.	Lee `code`.
`403`	Cuenta suspendida, o un trabajo que no es tuyo.	Contacta con el soporte o revisa el ID del trabajo.
`404`	No encontrado.	Comprueba el ID o el camino.
`409`	Se ha alcanzado la solicitud duplicada o el límite.	Lee `code`.
`413`	Este renderizado costaría más que el límite por renderizado.	Usa menos escenas o un `quality` más bajo.
`422`	El render no tiene marca, producto ni presentador que lo ancle.	Ver vídeos de realización.
`429`	Demasiadas peticiones o demasiados renderizados a la vez.	Espera y vuelve a intentarlo. Ver límites.
`500`	Algo salió mal de nuestro lado.	Inténtalo después.
`502`	La planificación de tu informe falló. Los créditos de planificación fueron devueltos.	Reinténtalo o reredacta el resumen.
`503`	La entrega se pausa o un servicio está caído. No se cobró nada.	Inténtalo después.

Un camino desconocido bajo /v1/ regresa 404 con code: "NOT_FOUND".

Códigos de error

Autenticación y plan

Código	Estado	Significado
`NO_API_KEY`	401	No hay `Authorization` cabecera, o el token no empieza con `emp_`.
`INVALID_API_KEY`	401	La clave es desconocida o revocada.
`PLAN_UPGRADE_REQUIRED`	402	API acceso necesita el plan Agency.
`ACCOUNT_SUSPENDED`	403	La cuenta está suspendida.

Créditos y uso

Código	Estado	Significado
`NO_CREDITS`	402	La cuenta no tiene créditos restantes.
`INSUFFICIENT_CREDITS`	402	No hay suficientes créditos para este render.
`ABUSE_CAP_EXCEEDED`	402	Se alcanza el límite mensual de uso del plan.
`STORAGE_FULL`	402	La biblioteca de vídeos de la cuenta está llena. Elimina algunos vídeos.
`UPGRADE_REQUIRED`	402	El vídeo necesita un plan de pago.
`REQUEST_COST_TOO_HIGH`	413	Este render costaría más que el límite por render.

Consulta Cuenta y facturación para créditos y planes.

Solicitudes de renderizado

Código	Estado	Significado
`CONTENT_BLOCKED`	400	El briefing o una escena infringe las reglas de contenido.
`PRODUCT_IMAGE_REQUIRED`	400	Este formato necesita `product_image_url`, o `product_enabled: false`.
`PRESENTER_REQUIRED`	400	Una escena de diálogo no tiene rostro. Añade `avatar_preset_id`, o envía `presenter_enabled: false`.
`UNSUPPORTED_MODEL`	400	Una escena pidió un modelo de render Reigniter no puede usar.
`BRAND_REQUIRED`	422	Se pidió una marca, pero no se encontró ninguna. Envía `brand_logo_url`.
`NO_ANCHOR`	422	No hay marca, foto de producto ni presentador. Añade uno o opta por no hacerlo.
`CANVAS_NOT_FOUND`	404	Un proyecto referenciado no está en esta cuenta.
`DUPLICATE_REQUEST`	409	Este `Idempotency-Key` ya estaba usado. No se cobró nada nuevo.
`PLAN_FAILED`	502	La planificación del informe fracasó. Se devolvieron los créditos de planificación.

Con un brief, un Idempotency-Key repetido también puede volver como 402 con el mensaje This request was already submitted. Trátalo como un duplicado, no como un problema de crédito.

Tipo de interés y concurrencia

Código	Estado	Significado
`RATE_LIMITED`	429	Demasiadas peticiones. Espera `retryAfter` (o `details.retryAfter`) segundos.
`CONCURRENT_LIMIT`	429	Demasiados renders ejecutándose a la vez. Espera a que uno termine.

Servicio

Código	Estado	Significado
`USAGE_CHECK_UNAVAILABLE`	503	No se pudo comprobar el uso, por lo que el renderizado se pausa. No se cobró nada.
`DB_UNAVAILABLE`	503	Un servicio está brevemente indisponible.
`FEATURE_NOT_AVAILABLE`	503	Ahora mismo no hay renderizado disponible.
`GLOBAL_KILL_SWITCH`	503	El renderizado está pausado para todos.
`FEATURE_KILL_SWITCH`	503	Esta función está pausada.
`USER_KILL_SWITCH`	503	Esta cuenta está temporalmente restringida. Contacta con el soporte.

Ganchos de red

Código	Estado	Significado
`UNKNOWN_EVENT`	400	No es un evento al que puedas suscribirte. La respuesta lista los válidos.
`URL_NOT_DELIVERABLE`	400	La URL no es una dirección http pública(s).
`HOOK_LIMIT`	409	La cuenta ya tiene el número máximo de webhooks.

Reintentar de forma segura

Reprueba 429, 500, 502 y 503 con retroceso. No vuelvas a intentar otros 4xx sin cambios.
Siempre envía un Idempotency-Key sobre POST /v1/render.
Sin respuesta (un tiempo de espera o una conexión caída): intenta de nuevo con la misma clave. Si la primera petición inicia un renderizado, se rechaza el intento en lugar de iniciar una segunda.
Respuesta a error: no se inició ningún renderizado para esa petición. Arregla la causa y luego inténtalo de nuevo con una nueva clave, porque una petición que falló a mitad puede que ya haya usado su clave. Los créditos de renderizado se reembolsan. El único cargo que no se reembolsa es la planificación breve, cuando el renderizado previsto es rechazado (ver Creación de vídeos).
Si una rendición fue aceptada (202) y luego falla, la status del trabajo se convierte en failed y error explica por qué. Los créditos por trabajos que no se realizaron se devuelven.