---
title: Errores
description: El formato único de errores de la API de Clipia — campos type, code y message, la tabla de estados HTTP y códigos, qué reintentar y cómo leer message.
icon: TriangleAlert
---

Todos los errores de la API REST usan el mismo formato: un objeto `error` con los campos `type`, `code` y `message`. El estado HTTP determina la clase de error; `code` es el motivo legible por máquina. Solo merece la pena reintentar tras una pausa los errores transitorios: `409 request_in_progress`, `429`, `500` y `503`.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid or revoked API key."
  }
}
```

Base su lógica en `code`. El campo `message` está pensado para personas y puede cambiar. En `400 invalid_request`, `message` incluye un detalle breve como `prompt_required` o `webhook_url_invalid`; la lista completa para el envío de generaciones está en [Enviar una generación](/es/docs/api-reference/submit#submit-errors).

A veces `error` incluye `retry_after_ms` o `retry_after_seconds`: una indicación de cuándo reintentar.

## Códigos

| HTTP | `code` | `type` | Cuándo | Reintento |
|------|--------|--------|--------|-----------|
| `400` | `invalid_request` | `invalid_request_error` | cuerpo, parámetros o ID no válidos; el motivo está en `message` | no, corrija la solicitud |
| `401` | `invalid_api_key` | `authentication_error` | la clave falta, es incorrecta o está revocada | no |
| `402` | `insufficient_credits` | `billing_error` | no hay créditos suficientes, o la cuenta nunca ha comprado créditos (clave live) | tras recargar |
| `402` | `subscription_required` | `billing_error` | esta operación requiere una suscripción activa | tras suscribirse |
| `403` | `insufficient_scope` | `permission_error` | la clave no tiene el permiso necesario | no |
| `404` | `not_found` | `invalid_request_error` | no existe el modelo (`model_not_found`) o la solicitud (`request_not_found`) | no |
| `409` | `idempotency_key_reuse` | `idempotency_error` | la misma `Idempotency-Key` con un cuerpo distinto | no, cambie la clave |
| `409` | `request_in_progress` | `idempotency_error` | un reintento mientras la primera solicitud aún se procesa | sí, en unos segundos |
| `422` | `model_input_invalid` | `invalid_request_error` | los parámetros no son válidos para el modelo | no, corrija `input` |
| `429` | `rate_limit_exceeded` | `rate_limit_error` | se ha superado el límite de frecuencia de solicitudes | sí, tras `Retry-After` |
| `429` | `concurrency_limit_exceeded` | `api_error` | se ha superado el límite de generaciones simultáneas, si está configurado | sí, cuando termine un trabajo |
| `500` | `internal_error` | `api_error` | error interno | sí, con pausas crecientes |
| `503` | `service_unavailable` | `api_error` | servicio no disponible temporalmente | sí, con pausas crecientes |

Los errores de [AI Gateway](/es/docs/llm-gateway) (`/v1/chat/completions` y los endpoints relacionados) usan el formato de OpenAI; sus códigos se enumeran en [Chat Completions](/es/docs/llm-gateway/chat-completions).

## Reintentos

<Callout type="info" title="Qué reintentar">
Reintente `429`, `500` y `503` con pausas crecientes: 1, 2, 4, 8 segundos, como máximo 5 intentos. En `429`, espere el tiempo que indique `Retry-After`. Reintente el envío de una generación con la misma `Idempotency-Key` para que el reintento no cree un segundo trabajo. Los demás errores `4xx`, salvo `409 request_in_progress` y `429`, se repiten sin cambios si reenvía la misma solicitud.
</Callout>

<Callout type="warn" title="Sin detalles internos">
Los mensajes de error no revelan la infraestructura interna. En `500` y `503` el texto es genérico: "An internal error occurred. Please retry or contact support." y "Service temporarily unavailable. Please retry later."
</Callout>

Una generación fallida no es un error HTTP: la solicitud del resultado devuelve `200` con `status: "FAILED"` y un objeto `error`, y los créditos vuelven a su saldo. Consulte [Resultado](/es/docs/api-reference/result).