Errores
Todos los endpoints fallan de la misma forma: 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 con base en esto. |
code |
Motivo exacto, estable y legible por máquinas. Cada código tiene una sección abajo; doc_url enlaza a ella. |
message |
Explicación legible para humanos, segura para registrar o mostrar a un desarrollador. |
param |
El parámetro de entrada o encabezado con el problema, cuando existe. |
details |
Para errores de entrada, cada problema encontrado: [{ "param", "message" }]. |
request_id |
La solicitud relacionada, 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 | Verifica el id del modelo o de la solicitud. |
insufficient_credits |
402 | Haz una recarga del saldo de API (top_up_url en el error). |
budget_exceeded |
402 | El presupuesto propio de la clave se agotó. Solución final: 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. Reintenta más tarde. |
internal_error |
500 | Es un error nuestro. Reintenta; si persiste, contacta a soporte con la hora y request_id. |
Códigos
invalid_request
Solicitud malformada genérica (400).
invalid_json
El cuerpo no es JSON válido (400).
invalid_body
El cuerpo es JSON válido, pero no es un objeto; la entrada del modelo debe ser un objeto JSON (400).
body_too_large
El cuerpo supera 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 indica cuál es.
invalid_category
GET /openapi.json?category= indica una categoría inexistente (400). GET https://api.doitong.com/v1/categories las enumera.
invalid_cursor
El cursor de una llamada de lista no pertenece a esta lista (400). Comienza de nuevo sin cursor.
invalid_idempotency_key
El encabezado Idempotency-Key está vacío o supera 255 caracteres (400).
invalid_arguments
Una llamada a una herramienta MCP tiene un argumento faltante o malformado (solo MCP). param indica 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 faltante, un tipo incorrecto, un valor fuera de la lista o el rango permitido, o se proporcionaron
los nombres canónico y nativo con valores distintos. 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 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 expiró (401).
insufficient_scope
A la clave le falta el alcance que necesita esta llamada (403), por ejemplo models:run para una ejecución 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.com/v1/models.
request_not_found
No existe una 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, 1,000 créditos de API = $1 — no son los créditos de las aplicaciones de Doitong) no cubre
el precio de esta llamada (402). La respuesta se envía antes de cobrar algo. El error incluye top_up_url; agrega fondos en
https://doitong.com/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.com/developers/dashboard#balance",
"top_up_url": "https://doitong.com/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }budget_exceeded
La llamada excedería el presupuesto propio de la clave de API en créditos de API (402). El propietario de la clave establece el presupuesto; 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 usó con un cuerpo diferente (409). Usa una clave nueva para una operación nueva.
idempotency_in_progress
Se está creando una solicitud con la misma Idempotency-Key (409). Reintenta en un momento para obtenerla.
request_active
La solicitud aún está queued o running, por lo que todavía no tiene archivos para eliminar (409). Elimínalos cuando termine.
not_cancelable
La solicitud ya está succeeded o failed y no se puede cancelar (409).
rate_limited
La clave hizo 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). Los créditos de API
se reembolsan. Si el 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á un resultado. Termina como failed con este código
(tipo upstream_error) y recibe un reembolso. Ejecútala de nuevo.
timeout
La solicitud se ejecutó más tiempo del 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). Reintenta más tarde.
internal_error
Algo falló de nuestro lado (500). Reintenta; si persiste, contacta a soporte.
charge_failed
No se pudo cobrar a la cuenta por un problema interno (500). La solicitud se marca como failed; no se retiró nada. Reintenta.
pricing_unavailable
El precio del modelo no está configurado, así que no se puede cotizar ni ejecutar en este momento (500).