Errores

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

{
  "detail": "Company not found"
}

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

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

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

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

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

# 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