Errores — Clipia Docs

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.

{
  "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.

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 (/v1/chat/completions y los endpoints relacionados) usan el formato de OpenAI; sus códigos se enumeran en Chat Completions.

Reintentos

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.

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."

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.

Códigos

Reintentos

En esta página