# Errores

> Códigos de estado HTTP y formato de respuesta de error

Source: https://docs.graph8.com/es/developers/errors/

La API utiliza códigos de estado HTTP estándar para indicar éxito o error. Las respuestas de error incluyen un campo `detail` con un mensaje legible para personas.

---

## Formato de respuesta de error

```json
{
  "detail": "Company not found"
}
```

Para errores de validación, la respuesta incluye detalles a nivel de campo:

```json
{
  "detail": [
    {
      "loc": ["body", "work_email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}
```

---

## Códigos de estado

### Éxito

| Código | Significado | Usado por |
|--------|-------------|-----------|
| `200` | OK | GET, PATCH, DELETE |
| `201` | Creado | POST |

### Errores del cliente

| Código | Significado | Causas comunes |
|--------|-------------|----------------|
| `400` | Solicitud incorrecta | Faltan campos requeridos, valores de campo inválidos, ningún campo en la actualización |
| `401` | No autorizado | API key ausente o inválida, API key expirada, se proporcionó un token JWT en lugar de una API key. El encabezado `X-Error-Code` (y el `code` del cuerpo) es `api_key_expired` para una API key expirada y `api_key_invalid` en los demás casos: rote la key expirada, no la reintente. |
| `404` | No encontrado | El recurso no existe o fue eliminado |
| `422` | Entidad no procesable | El cuerpo de la solicitud no supera la validación (tipos incorrectos, formato de correo inválido) |
| `429` | Demasiadas solicitudes | Límite de tasa excedido. Consulte [Límites de tasa](https://docs.graph8.com/developers/rate-limits/) |

### Errores del servidor

| Código | Significado | Acción |
|--------|-------------|--------|
| `500` | Error interno del servidor | Reintente con retroceso exponencial. Si persiste, contacte al soporte. |

---

## Manejo de errores

**Python**

```python
response = requests.get(f"{BASE_URL}/contacts/99999", headers=HEADERS)

if response.status_code == 200:
    contact = response.json()["data"]
elif response.status_code == 404:
    print("Contact not found")
elif response.status_code == 401:
    print("Check your API key")
elif response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 5))
    print(f"Rate limited. Retry after {retry_after}s")
else:
    print(f"Error {response.status_code}: {response.json()}")
```

**TypeScript**

```typescript
const response = await fetch(`${BASE_URL}/contacts/99999`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});

if (response.ok) {
  const { data: contact } = await response.json();
} else if (response.status === 404) {
  console.error("Contact not found");
} else if (response.status === 401) {
  console.error("Check your API key");
} else if (response.status === 429) {
  const retryAfter = response.headers.get("Retry-After") || "5";
  console.error(`Rate limited. Retry after ${retryAfter}s`);
} else {
  const error = await response.json();
  console.error(`Error ${response.status}:`, error);
}
```

**cURL**

```bash
# Use -w to print the HTTP status code
curl -s -w "\nHTTP Status: %{http_code}\n" \
  "https://be.graph8.com/api/v1/contacts/99999" \
  -H "Authorization: Bearer $API_KEY"
```

---

## Escenarios de error comunes

### Autenticación

| Error | Causa | Solución |
|-------|-------|----------|
| `Missing Authorization header` | No se envió el encabezado `Authorization` | Agregue `Authorization: Bearer <api_key>` |
| `JWT token provided instead of API key` | Se proporcionó un token de sesión del navegador | Use una API key de organización desde Configuración > API |
| `API key not associated with an organization` | La clave tiene un formato incorrecto o fue revocada | Cree una nueva clave en Configuración > API |

### Contactos

| Error | Causa | Solución |
|-------|-------|----------|
| `list_id is required when creating contacts` | POST /contacts sin `list_id` | Incluya `list_id`. Cada contacto debe pertenecer a una lista |
| `Contact not found` | El ID del contacto no existe o fue eliminado | Verifique el ID del contacto |

### Empresas

| Error | Causa | Solución |
|-------|-------|----------|
| `Company not found` | El ID de la empresa no existe o fue eliminado | Verifique el ID de la empresa |
| `No fields to update` | PATCH con cuerpo vacío | Incluya al menos un campo para actualizar |

### Listas

| Error | Causa | Solución |
|-------|-------|----------|
| `Invalid list type` | POST /lists con un `type` no reconocido | Use: `contacts`, `companies`, `suppressions`, `deals`, `leads` |
| `List not found` | El ID de la lista no existe o fue eliminado | Verifique el ID de la lista |