Errores
Cada endpoint falla de la misma manera: un estado HTTP y un sobre JSON.
{
"error": {
"type": "invalid_request",
"code": "invalid_input",
"message": "duration must be one of 5, 10.",
"param": "duration",
"details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ],
"request_id": null,
"doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
}
}| Campo | Significado |
|---|---|
type |
Clase general del error. Decide qué hacer a partir de esto. |
code |
Motivo exacto, estable y legible por máquinas. Cada código tiene una sección más abajo; doc_url enlaza con ella. |
message |
Explicación legible, segura para registrar o mostrar a un desarrollador. |
param |
El parámetro de entrada o encabezado responsable, cuando existe. |
details |
Para errores de entrada, todos los problemas encontrados: [{ "param", "message" }]. |
request_id |
La solicitud a la que se refiere, cuando existe. |
No se cobra nada por una llamada que devuelve un error. Una solicitud que falla después de ser aceptada conserva el estado
failed, incluye error: { "type", "code", "message" } en el objeto de la solicitud y recibe un reembolso automático.
Tipos
| Tipo | Estado HTTP | Qué hacer |
|---|---|---|
invalid_request |
400, 413 o 422 | Corrige la solicitud. Reintentar la misma llamada volverá a fallar. |
authentication_error |
401 | Envía una clave válida en Authorization: Bearer <key>. |
permission_error |
403 | Usa una clave con el alcance necesario. |
not_found |
404 | Comprueba el id del modelo o de la solicitud. |
insufficient_credits |
402 | Recarga el saldo de API (top_up_url en el error). |
budget_exceeded |
402 | El presupuesto propio de la clave se ha agotado. Definitivo: pide al propietario de la clave que lo aumente. |
conflict |
409 | El recurso no está en un estado que permita esta llamada. |
rate_limited |
429 | Espera Retry-After segundos y vuelve a intentarlo. |
upstream_error |
502 | El backend del modelo falló. Es seguro reintentar con la misma Idempotency-Key: se ejecutará de nuevo; no se te cobró. |
service_unavailable |
503 | La API está pausada o una dependencia no está disponible. Reinténtalo más tarde. |
internal_error |
500 | Es un error nuestro. Reinténtalo; si persiste, contacta con soporte indicando la hora y request_id. |
Códigos
invalid_request
Solicitud mal formada genérica (400).
invalid_json
El cuerpo no es un JSON válido (400).
invalid_body
El cuerpo es un JSON válido, pero no es un objeto; la entrada del modelo debe ser un objeto JSON (400).
body_too_large
El cuerpo supera los 16 MB (413). Sube los archivos grandes y pasa su URL en su lugar (consulta Archivos).
invalid_parameter
Un parámetro de consulta tiene un valor incorrecto, por ejemplo limit fuera de 1 a 100, wait no es un número, un
status o category desconocido, o storage distinto de permanent / temporary (400). param lo identifica.
invalid_category
GET /openapi.json?category= indica una categoría inexistente (400). GET https://api.doitong.ru/v1/categories las enumera.
invalid_cursor
El cursor de una llamada de lista no pertenece a esta lista (400). Empieza de nuevo sin cursor.
invalid_idempotency_key
El encabezado Idempotency-Key está vacío o supera los 255 caracteres (400).
invalid_arguments
Una llamada a una herramienta MCP tiene un argumento ausente o mal formado (solo MCP). param identifica el argumento.
invalid_input
La entrada del modelo no supera la validación (422): un parámetro desconocido (el mensaje sugiere el nombre válido más cercano),
un parámetro obligatorio ausente, un tipo incorrecto, un valor fuera de la lista o el intervalo permitidos, o se han indicado tanto el nombre canónico como el nativo con valores diferentes. param es el primer parámetro problemático y details los enumera todos.
No se cobra nada.
unsupported_file
Un archivo tiene un tipo que no aceptamos (422), por ejemplo una carga con una extensión no compatible o un content_type
que no coincide con la extensión.
invalid_webhook_url
webhook_url no es una URL pública https:// (422). Se rechazan las direcciones privadas, locales y http:// sin cifrado.
missing_api_key
El endpoint necesita una clave de API y no se envió ninguna (401).
invalid_api_key
La clave es desconocida, fue revocada o ha caducado (401).
insufficient_scope
A la clave le falta el alcance que necesita esta llamada (403), por ejemplo models:run para ejecutar, o models:read para leer
solicitudes y el saldo. Consulta Autenticación.
account_disabled
La cuenta está cerrada o suspendida (403). Sus claves ya no funcionan.
not_found
La ruta no existe (404).
model_not_found
Ningún modelo público tiene este id (404). Enumera los modelos con GET https://api.doitong.ru/v1/models.
request_not_found
No existe ninguna solicitud con este id en tu cuenta (404). Las solicitudes de otras cuentas nunca son visibles.
insufficient_credits
El saldo de API de la cuenta (créditos de API, 1000 créditos de API = 1 $ — no los créditos de las aplicaciones de Doitong) no cubre
el precio de esta llamada (402). La respuesta se envía antes de cobrar nada. El error incluye top_up_url; añade dinero
en https://doitong.ru/developers/dashboard#balance y vuelve a intentarlo.
{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
"message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.ru/developers/dashboard#balance",
"top_up_url": "https://doitong.ru/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }budget_exceeded
La llamada superaría el presupuesto propio de la clave de API en créditos de API (402). El presupuesto lo establece el propietario de la clave; reintentar no sirve hasta que lo aumente.
conflict
La llamada entra en conflicto con el estado actual del recurso (409).
idempotency_mismatch
Idempotency-Key ya se utilizó con un cuerpo diferente (409). Usa una clave nueva para una operación nueva.
idempotency_in_progress
Ahora mismo se está creando una solicitud con la misma Idempotency-Key (409). Reinténtalo dentro de un momento para obtenerla.
request_active
La solicitud todavía está queued o running, por lo que aún no tiene archivos que eliminar (409). Elimínalos cuando haya terminado.
not_cancelable
La solicitud ya está succeeded o failed y no se puede cancelar (409).
rate_limited
La clave realizó demasiadas solicitudes en la ventana actual (429). Consulta los encabezados X-RateLimit-* y Retry-After.
too_many_inflight
La cuenta ya tiene 10 solicitudes queued o running (429). Inicia la siguiente cuando termine una de ellas.
upstream_error
El backend del modelo rechazó o no pudo procesar la solicitud (502 al ejecutar, o failed con este código en la solicitud). Se reembolsan los créditos de API. Si el propio backend rechazó la entrada, la llamada devuelve 422 invalid_input con su mensaje.
upstream_lost
El backend del modelo ya no conoce la solicitud, por lo que nunca llegará ningún resultado. Termina como failed con este código
(tipo upstream_error) y recibe un reembolso. Ejecútala de nuevo.
timeout
La solicitud superó su límite (15 minutos para imágenes, 60 para video, 30 en los demás casos) y se detuvo. Termina como
failed con este código y recibe un reembolso.
service_unavailable
La API está pausada temporalmente o una dependencia, como la carga de archivos, no está disponible (503). Reinténtalo más tarde.
internal_error
Algo falló de nuestro lado (500). Reinténtalo; si persiste, contacta con soporte.
charge_failed
No se pudo cobrar a la cuenta debido a un problema interno (500). La solicitud se marca como failed; no se retiró nada. Reinténtalo.
pricing_unavailable
El precio del modelo no está configurado, por lo que ahora no se puede calcular ni ejecutar (500).