0Pricing
AI Agents · Lección

Gestión de respuestas y errores de API

Analice respuestas JSON, códigos de error y patrones de gestión de excepciones.

Gestión de respuestas y errores de API es una lección gratuita de AI Agents en CoddyKit. Esta es la lección 3 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Agents, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Agents incluye 4 lecciones en total.

El objeto Response

Cada llamada a requests devuelve un objeto Response. Contiene todo lo que el servidor ha enviado: el código de estado, los encabezados y el cuerpo. Antes de procesar el cuerpo, inspeccione siempre el código de estado: una respuesta con estado 500 sigue teniendo un cuerpo, pero no contendrá los datos que necesita.

import requests

response = requests.get('https://api.example.com/data')

# Key attributes of the response
print(response.status_code)       # e.g. 200
print(response.headers)           # dict of response headers
print(response.headers.get('Content-Type'))  # 'application/json'
print(response.text)              # raw response body as string
print(response.content)           # raw bytes

Análisis de JSON con response.json()

Llame a response.json() para analizar automáticamente el cuerpo de la respuesta como JSON y convertirlo en un diccionario o una lista de Python. Es equivalente a json.loads(response.text), pero también valida que el Content-Type sea adecuado.

Llame a .json() únicamente cuando sepa que la respuesta realmente es JSON; compruebe primero el encabezado Content-Type.

import requests

response = requests.get(
    'https://api.example.com/users/42',
    headers={'Authorization': 'Bearer YOUR_KEY'}
)

# Parse JSON body
user = response.json()

# Access fields safely with .get()
name = user.get('name', 'Unknown')
email = user.get('email', '')
roles = user.get('roles', [])

print(f'User: {name} ({email})')
print(f'Roles: {roles}')

Comprobación de status_code antes del análisis

No llame nunca a response.json() sin confirmar primero que la solicitud se ha realizado correctamente. Las respuestas de error (4xx/5xx) suelen devolver detalles del error en JSON, lo que resulta útil para la depuración, pero no son los datos que necesita. Compruebe siempre status_code primero.

import requests

response = requests.post(
    'https://api.example.com/tasks',
    json={'title': 'Write report'},
    headers={'Authorization': 'Bearer YOUR_KEY'}
)

if response.status_code == 201:
    task = response.json()
    print('Task created, ID:', task['id'])
elif response.status_code == 400:
    error = response.json()
    print('Validation error:', error.get('message'))
elif response.status_code == 401:
    print('Auth failed — check your token')
else:
    print(f'Unexpected status {response.status_code}: {response.text[:200]}')

raise_for_status() — generación automática de errores

response.raise_for_status() genera automáticamente una excepción HTTPError si el código de estado es 4xx o 5xx. Es una forma limpia de convertir las respuestas HTTP incorrectas en excepciones de Python, lo que le permite utilizar try/except en lugar de largas cadenas de if/elif.

import requests
from requests.exceptions import HTTPError

try:
    response = requests.get(
        'https://api.example.com/users/9999',
        headers={'Authorization': 'Bearer YOUR_KEY'}
    )
    response.raise_for_status()  # raises if status >= 400
    user = response.json()
    print('Found user:', user['name'])

except HTTPError as e:
    print(f'HTTP error: {e.response.status_code}')
    print('Details:', e.response.text[:300])

Gestión de JSONDecodeError

A veces una API devuelve una respuesta que no es JSON cuando usted espera JSON: una página de error del servidor en HTML, un cuerpo vacío o un archivo binario. Llamar a response.json() en estos casos genera json.JSONDecodeError. Capture siempre esta excepción para evitar que el agente se cierre silenciosamente.

import requests
import json

response = requests.get(
    'https://api.example.com/report',
    headers={'Authorization': 'Bearer YOUR_KEY'}
)

try:
    data = response.json()
except json.JSONDecodeError as e:
    print(f'Response is not valid JSON: {e}')
    print('Content-Type:', response.headers.get('Content-Type'))
    print('First 200 chars:', response.text[:200])
    # Decide: is this an HTML error page? A CSV file?
    data = None

if data is None:
    print('Falling back to text processing')

ConnectionError — problemas de red

Se produce un ConnectionError cuando su agente no puede llegar al servidor en absoluto: un fallo de resolución de DNS, un servidor desconectado o un firewall que bloquea la solicitud. Es un fallo a nivel de red que ocurre antes de que tenga lugar cualquier comunicación HTTP.

A diferencia de un error 5xx, esta no es la respuesta del servidor: la conexión nunca llegó a establecerse.

import requests
from requests.exceptions import ConnectionError

try:
    response = requests.get('https://api.example.com/data')
    data = response.json()
except ConnectionError as e:
    print('Cannot reach server. Possible causes:')
    print('- DNS failure (bad hostname)')
    print('- Server is down')
    print('- No internet connection')
    print('- Firewall blocking the port')
    print(f'Error detail: {e}')
    # Consider: queue the request for retry when connectivity returns

Timeout — prevención de agentes bloqueados

De forma predeterminada, requests espera indefinidamente una respuesta. Un servidor lento o bloqueado puede congelar su agente indefinidamente. Establezca siempre un timeout: una tupla de (connect_timeout, read_timeout) en segundos. Se genera una excepción Timeout si el servidor no responde a tiempo.

import requests
from requests.exceptions import Timeout

try:
    response = requests.get(
        'https://api.example.com/slow-endpoint',
        headers={'Authorization': 'Bearer YOUR_KEY'},
        timeout=(5, 30)  # 5s to connect, 30s to read
    )
    data = response.json()
except Timeout:
    print('Request timed out after 30 seconds')
    print('Options: retry, use cached result, or alert operator')

Gestión integral de excepciones

En los agentes de producción, capture todas las excepciones de requests siguiendo una jerarquía coherente. requests.exceptions.RequestException es la clase base de todos los errores de requests; capturarla le proporciona una red de seguridad frente a problemas de red inesperados.

import requests
import json
from requests.exceptions import (
    ConnectionError, Timeout, HTTPError, RequestException
)

def safe_api_call(url, headers):
    try:
        r = requests.get(url, headers=headers, timeout=(5, 30))
        r.raise_for_status()
        return r.json()
    except Timeout:
        print('ERROR: Request timed out')
    except ConnectionError:
        print('ERROR: Cannot reach server')
    except HTTPError as e:
        print(f'ERROR: HTTP {e.response.status_code}')
        try:
            print('API error:', e.response.json().get('message'))
        except json.JSONDecodeError:
            print('Non-JSON error body')
    except RequestException as e:
        print(f'ERROR: Unexpected request error: {e}')
    return None

Registro de respuestas para la depuración

Cuando un agente se comporta de forma incorrecta, necesita suficiente contexto para diagnosticarlo. Registre el método de la solicitud, la URL, el código de estado y los detalles relevantes de la respuesta, pero no registre nunca las claves de API. Utilice el módulo integrado logging de Python en lugar de instrucciones print para los agentes de producción.

import logging
import requests

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger('agent.api')

def logged_request(method, url, **kwargs):
    logger.info(f'-> {method.upper()} {url}')
    response = requests.request(method, url, **kwargs)
    logger.info(
        f'<- {response.status_code} '
        f'({len(response.content)} bytes) '
        f'{response.elapsed.total_seconds():.2f}s'
    )
    if response.status_code >= 400:
        logger.error(f'Error body: {response.text[:500]}')
    return response

Gestión de respuestas paginadas

Muchas API devuelven los datos en páginas. Su agente debe seguir los enlaces de paginación para obtener todos los resultados. Busque una URL next en la respuesta o un campo page/cursor, y repita el proceso hasta que no queden más páginas.

import requests

def get_all_items(base_url, headers):
    all_items = []
    url = f'{base_url}/items?page=1&limit=100'

    while url:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        data = response.json()

        all_items.extend(data.get('items', []))

        # Follow 'next' link if present
        url = data.get('next_page_url')  # None stops the loop

        print(f'Fetched {len(all_items)} items so far...')

    print(f'Total: {len(all_items)} items')
    return all_items

Transmisión de respuestas grandes

Para respuestas grandes (archivos, salidas extensas de IA), utilice stream=True para evitar cargar toda la respuesta en la memoria de una sola vez. Lea la respuesta por fragmentos. Esto es esencial cuando su agente procesa conjuntos de datos grandes o transmite texto generado por IA.

import requests

response = requests.get(
    'https://api.example.com/large-report',
    headers={'Authorization': 'Bearer YOUR_KEY'},
    stream=True
)

response.raise_for_status()

# Write streamed content to file
with open('report.json', 'wb') as f:
    for chunk in response.iter_content(chunk_size=8192):
        if chunk:
            f.write(chunk)

print('Download complete')

# For streaming JSON lines (NDJSON):
for line in response.iter_lines():
    if line:
        import json
        record = json.loads(line)
        print(record)

Comprobación rápida: raise_for_status

Compruebe cuánto ha comprendido sobre la gestión de errores en las respuestas.

Resumen de la gestión de respuestas

Una gestión sólida de las respuestas es lo que diferencia a un agente frágil de uno fiable:

  • Compruebe siempre status_code antes de analizar el cuerpo
  • Utilice response.json() para analizar la respuesta y capture JSONDecodeError si el cuerpo podría no ser JSON
  • Utilice raise_for_status() para convertir los errores HTTP en excepciones
  • Capture ConnectionError para los fallos de red y Timeout para los servidores lentos
  • Establezca siempre una tupla timeout=(connect, read) en cada solicitud
  • Registre las solicitudes y las respuestas (sin incluir las claves) para facilitar la depuración

Preguntas frecuentes

¿La lección «Gestión de respuestas y errores de API» es gratis?

Sí — el texto completo de «Gestión de respuestas y errores de API» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Agents, actualiza a CoddyKit PRO. El curso de AI Agents incluye 4 lecciones en total.

¿Qué aprenderé en «Gestión de respuestas y errores de API»?

Analice respuestas JSON, códigos de error y patrones de gestión de excepciones. Practicas AI Agents con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar AI Agents?

No se requiere experiencia previa. AI Agents en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 3 de 4.

¿Cuánto tiempo toma la lección «Gestión de respuestas y errores de API»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de AI Agents?

Sí. Cada lección de AI Agents incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Fundamentos de REST API para desarrolladores de agentes
  2. Autenticación: claves de API y OAuth
  3. Gestión de respuestas y errores de API
  4. Limitación de velocidad y lógica de reintentos
← Volver a AI Agents