Errores

​

Errores HTTP

Nuestra API sigue un formato predecible de códigos de error HTTP:

• 400 - invalid_request_error: Hubo un problema con el formato o contenido de tu solicitud. También podemos usar este tipo de error para otros códigos de estado 4XX no listados a continuación.

• 401 - authentication_error: Hay un problema con tu clave de API.

• 403 - permission_error: Tu clave de API no tiene permiso para usar el recurso especificado.

• 404 - not_found_error: No se encontró el recurso solicitado.

• 413 - request_too_large: La solicitud excede el número máximo permitido de bytes.

• 429 - rate_limit_error: Tu cuenta ha alcanzado un límite de velocidad.

• 500 - api_error: Ha ocurrido un error inesperado interno en los sistemas de Anthropic.

• 529 - overloaded_error: La API de Anthropic está temporalmente sobrecargada.

  Los aumentos repentinos y grandes en el uso pueden llevar a un incremento en la tasa de errores 529. Recomendamos aumentar gradualmente y mantener patrones de uso consistentes.

Al recibir una respuesta streaming a través de SSE, es posible que ocurra un error después de devolver una respuesta 200, en cuyo caso el manejo de errores no seguiría estos mecanismos estándar.

​

Formas de error

Los errores siempre se devuelven como JSON, con un objeto error de nivel superior que siempre incluye valores de type y message. Por ejemplo:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  }
}

De acuerdo con nuestra política de versionado, podemos expandir los valores dentro de estos objetos, y es posible que los valores de type aumenten con el tiempo.

​

ID de solicitud

Cada respuesta de la API incluye un encabezado único request-id. Este encabezado contiene un valor como req_018EeWyXxfu5pfWkrYcMdjWG. Cuando contactes al soporte sobre una solicitud específica, por favor incluye este ID para ayudarnos a resolver tu problema rápidamente.

Nuestros SDK oficiales proporcionan este valor como una propiedad en los objetos de respuesta de nivel superior, conteniendo el valor del encabezado x-request-id:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ]
)
print(f"Request ID: {message._request_id}")

​

Solicitudes largas

No recomendamos establecer valores grandes de max_tokens sin usar nuestra API de Mensajes por streaming o API de Lotes de Mensajes:

• Algunas redes pueden cerrar conexiones inactivas después de un período de tiempo variable, lo que puede causar que la solicitud falle o se agote el tiempo de espera sin recibir una respuesta de Anthropic.
• Las redes difieren en fiabilidad; nuestra API de Lotes de Mensajes puede ayudarte a gestionar el riesgo de problemas de red permitiéndote sondear los resultados en lugar de requerir una conexión de red ininterrumpida.

Si estás construyendo una integración directa con la API, debes tener en cuenta que establecer un keep-alive del socket TCP puede reducir el impacto de los tiempos de espera de conexión inactiva en algunas redes.

Nuestros SDK validarán que tus solicitudes de la API de Mensajes sin streaming no se espera que excedan un tiempo de espera de 10 minutos y también establecerán una opción de socket para keep-alive TCP.