# Errores Cada endpoint falla de la misma manera: un estado HTTP y un sobre JSON. ```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 `. | | `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](https://doitong.com/developers/docs/files)). ### `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.com/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](https://doitong.com/developers/docs/authentication#scopes). ### `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 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.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) y vuelve a intentarlo. ```json { "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 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).