Referencia de la API

Errores y límites

Formato del error

El error sigue el formato de la ruta llamada. En /v1/chat/completions, type y code traen el mismo código. Los mensajes están en portugués.

OpenAI · /v1/chat/completions

{
  "error": {
    "message": "Saldo insuficiente.",
    "type": "sem_saldo",
    "code": "sem_saldo"
  }
}

Anthropic · /v1/messages

{
  "type": "error",
  "error": {
    "type": "billing_error",
    "message": "Saldo insuficiente."
  }
}

Códigos

HTTP	Código	Causa
400	`invalido`	JSON inválido, messages ausente, n distinto de 1, o parámetro rechazado por el modelo.
400	`sem_visao`	Imagen enviada a un modelo sin visión.
401	`chave_invalida`	Clave ausente, mal formada o inexistente.
401	`chave_revogada`	Clave revocada en la consola.
401	`chave_expirada`	Clave pasada de su fecha de vencimiento.
402	`sem_saldo`	Saldo menor que la reserva de la solicitud.
402	`teto_chave`	Tope diario o mensual de la clave alcanzado.
403	`termos`	Términos de uso aún no aceptados. Se aceptan en el chat o en la consola, en el primer acceso.
403	`restrito`	Cuenta aún sin acceso a la API. Hasta el lanzamiento, la API atiende solo al equipo.
403	`modelo_nao_permitido`	Modelo fuera de la lista permitida de la clave.
403	`conta_bloqueada`	Cuenta bloqueada.
404	`modelo`	Modelo no encontrado. El mensaje lista los ids disponibles.
413	`grande`	Cuerpo de la solicitud por encima del límite.
429	`limite_minuto`	Límite de solicitudes por minuto de la cuenta.
429	`limite_simultaneo`	Límite de solicitudes simultáneas de la cuenta.
429	`muitas_falhas`	Demasiados intentos con clave inválida desde la misma IP. Incluye Retry-After.
429	`modelo_sobrecarregado`	Modelo sobrecargado. Intenta de nuevo en unos instantes.
502	`modelo_indisponivel`	Fallo al comunicarse con el modelo, o respuesta inválida.
503	`indisponivel`	Servicio no disponible.

Tipos en el formato Anthropic

En /v1/messages, error.type sigue el estado HTTP:

HTTP	error.type
400	`invalid_request_error`
401	`authentication_error`
402	`billing_error`
403	`permission_error`
404	`not_found_error`
413	`request_too_large`
429	`rate_limit_error`
502	`api_error`
503	`overloaded_error`

Límites

Límite	Valor	Al superarlo
Solicitudes por cuenta (todas las claves juntas)	60 por minuto	`429 limite_minuto`
Solicitudes simultáneas por cuenta (chat y API)	5	`429 limite_simultaneo`
Intentos con clave inválida por IP	20 en 10 minutos	`429 muitas_falhas`
Cuerpo de la solicitud	4 MB	`413 grande`
Duración de la solicitud	300 segundos	—
Respuestas por solicitud (n)	1	`400 invalido`
Gasto de la clave	Tope diario y mensual, opcional	`402 teto_chave`
Saldo	Reserva por solicitud	`402 sem_saldo`

El límite por minuto cuenta los últimos 60 segundos de la cuenta, solo en la API (el chat tiene el suyo). Una solicitud cuenta como simultánea hasta que termina su respuesta. muitas_falhas devuelve el encabezado Retry-After, en segundos.

Reintentos

429 y 502: intenta de nuevo con una espera creciente.
400, 401, 403, 404 y 413: corrige la solicitud antes de repetir.
402: recarga el saldo o sube el tope de la clave en la consola.

Una solicitud que el modelo responde con error HTTP, o que no llega al modelo, no se cobra. Ver Facturación.