Documentación para desarrolladoresPrimeros pasos
Errores
Una única estructura de error, códigos estables y reglas de reintento claras.
Todas las respuestas que no son 2xx tienen la misma estructura. Basa tu lógica en error.code, nunca en message.
{
"error": {
"code": "validation_failed",
"message": "The request is invalid.",
"request_id": "req_8fK2Lq9ZtX4mN7bV1cW3yH6p",
"details": [
{
"path": "items[3].length",
"code": "out_of_range",
"message": "length must be greater than 0."
}
]
}
}| Campo | Contenido |
|---|---|
code | Estable, en snake_case |
message | En inglés, para los registros |
request_id | También en X-Request-Id. Indícalo al soporte |
details[] | En 400/422: path, code y message de cada problema |
Códigos
| Estado | Código | Significado | Qué hacer | Reintentar |
|---|---|---|---|---|
| 400 | invalid_json | El cuerpo no es JSON válido o un campo tiene un tipo incorrecto. | Corrige el cuerpo de la solicitud. | No |
| 401 | unauthorized | Clave de API ausente, mal formada o desconocida. | Envía Authorization: Bearer cd_live_…; comprueba que copiaste la clave completa. | No |
| 401 | key_revoked | La clave se ha revocado. | Crea una clave nueva en la consola de desarrolladores. | No |
| 401 | key_expired | La clave ha superado su fecha de caducidad. | Crea una clave nueva en la consola de desarrolladores. | No |
| 402 | insufficient_credits | Los créditos disponibles no cubren el coste mínimo posible de este trabajo. | Compra una recarga de créditos o espera a los créditos mensuales; no se ha cobrado nada. | No |
| 403 | ip_not_allowed | La IP de origen no está en la lista de IP permitidas de la clave. | Llama desde una IP permitida o edita la lista de IP permitidas. | No |
| 403 | subscription_inactive | La organización no tiene ninguna suscripción activa que incluya la API. | Renueva la suscripción. | No |
| 403 | account_inactive | La organización está suspendida o no tiene ningún propietario con la cuenta activa. | Contacta con el soporte. | No |
| 403 | scope_missing | A la clave le falta un permiso que requiere este endpoint. | Usa una clave con el permiso necesario (pack:write, jobs:read, account:read, resources:read, resources:write). | No |
| 403 | preset_read_only | Los vehículos predefinidos no se pueden modificar ni eliminar. | Crea tu propio vehículo con POST /v1/vehicles. | No |
| 403 | plan_limit_reached | El plan de la organización no permite más proyectos ni artículos de carga. | Elimina los proyectos que ya no necesites o cámbiate a un plan superior. | No |
| 404 | not_found | Ningún endpoint de /v1 tiene este método y esta ruta. | Comprueba el método y la ruta en la lista de endpoints. | No |
| 404 | job_not_found | No hay ningún trabajo con este ID en tu organización. | Comprueba el ID. | No |
| 404 | vehicle_not_found | No hay ningún vehículo con este ID entre los predefinidos ni entre los vehículos de tu organización. | Comprueba el ID con GET /v1/vehicles. | No |
| 404 | template_not_found | No hay ninguna plantilla con este ID en tu organización. | Comprueba el ID con GET /v1/templates. | No |
| 404 | project_not_found | No hay ningún proyecto con este ID en tu organización. | Comprueba el ID con GET /v1/projects. | No |
| 409 | job_not_finished | El trabajo sigue en cola o en curso. | Consulta GET /v1/jobs/{id} hasta que status sea succeeded. | Sí |
| 409 | project_busy | Se está calculando la carga del proyecto en este momento (en la aplicación o en otro trabajo). | Espera a que termine ese cálculo y vuelve a intentarlo. | Sí |
| 409 | job_failed | El trabajo ha fallado; no tiene resultado. | Lee job.error; los fallos por nuestra parte no se cobran (time_limit_exceeded se cobra como un trabajo cancelado). Vuelve a enviarlo si la causa era temporal. | No |
| 409 | job_canceled | El trabajo se canceló; no tiene resultado. | Vuelve a enviarlo si lo necesitas. | No |
| 409 | job_already_finished | El trabajo ya ha terminado y no se puede cancelar. | No hay nada que hacer. | No |
| 400 | idempotency_key_invalid | La cabecera Idempotency-Key tiene más de 128 caracteres. | Usa una clave más corta (un UUID sirve). | No |
| 410 | result_expired | El resultado superó el periodo de conservación y se eliminó. | Vuelve a enviar el trabajo si necesitas el plan de nuevo. | No |
| 413 | payload_too_large | El cuerpo de la solicitud supera los 10 MB. | Envía menos artículos o artículos más simples. | No |
| 422 | validation_failed | La solicitud es JSON bien formado, pero describe un trabajo no válido. details[] enumera todos los problemas. | Corrige cada details[].path; los errores de validación son gratuitos. | No |
| 429 | rate_limited | Demasiadas solicitudes en el minuto, la hora o el día en curso (por clave o por organización), o más de 60 autenticaciones fallidas por minuto desde tu dirección IP. | Espera los segundos que indica Retry-After y reintenta con backoff. | Sí |
| 429 | too_many_jobs | La organización ya tiene el número máximo de trabajos en cola + en curso. | Espera a que terminen los trabajos en curso y vuelve a intentarlo. | Sí |
| 500 | internal_error | Algo ha fallado por nuestra parte. | Reintenta con backoff; si persiste, indica el request_id al soporte. | Sí |
| 503 | api_disabled | La API está desactivada temporalmente (mantenimiento) o deshabilitada para la organización. | Vuelve a intentarlo más tarde. | Sí |
Detalles de validación
details[].code en 422 validation_failed:
| Código | Significado |
|---|---|
required | Falta un campo obligatorio |
invalid_value | Tipo incorrecto o valor no permitido |
out_of_range | Demasiado pequeño, demasiado grande o demasiado largo |
duplicate_id | Un ID se usa dos veces |
unknown_vehicle | No hay ningún vehículo predefinido ni tuyo con este vehicle_id |
unknown_template | No hay ninguna plantilla tuya con este template_id |
type_not_allowed | Tipo de vehículo no habilitado para tu organización |
unknown_group | Un artículo indica un grupo que no está en la lista |
does_not_fit | El artículo no cabe en ninguno de los vehículos indicados |
too_many_items | Más unidades de artículos que el límite por trabajo |
too_many_vehicles | Más vehículos que el límite por trabajo |
unknown_field | Un campo que la API no reconoce |
Errores de trabajo
Un trabajo failed o canceled indica el motivo en job.error.code:
| Código | Significado |
|---|---|
canceled | Cancelado con DELETE /v1/jobs/{id}. Se cobra la tarifa base + el cómputo usado. |
time_limit_exceeded | El presupuesto de cómputo se agotó antes de completar ningún vehículo. Se cobra como un trabajo cancelado: tarifa por trabajo, recargo por carga grande y cómputo usado, nunca la tarifa por vehículo. |
engine_failed | El motor de carga ha fallado. No se cobra. |
queue_timeout | El trabajo esperó demasiado a que quedara libre un hueco de cómputo. No se cobra. |
server_restarted | El servicio se reinició mientras el trabajo estaba en cola o en curso. No se cobra. |
Reintentos
Reintenta 429, 500 y 503 con backoff exponencial, respetando Retry-After. Envía la misma Idempotency-Key (Idempotencia). No reintentes nunca otros errores 4xx sin modificar la solicitud.