Errores y límites

Toda respuesta que no sea 2xx usa el mismo envelope. El request_id coincide con la cabecera X-Request-ID, y es lo que hace rastreable un fallo concreto.

El envelope

json

{
  "error": {
    "code": "not_found",
    "message": "Resource not found",
    "request_id": "b3f1c2a4-..."
  }
}

Los errores de validación devuelven 422 con code "validation_error". El message enumera los campos que fallan, en formato campo: motivo.

json

{
  "error": {
    "code": "validation_error",
    "message": "body.email: value is not a valid email address; body.name: field required",
    "request_id": "b3f1c2a4-..."
  }
}

Estado	Código	Cuándo sale
401	`unauthorized`	Token ausente, inválido o caducado.
403	`forbidden`	Autenticado, pero sin permiso para esa acción.
404	`not_found`	No existe, o no eres miembro de su organización.
409	`conflict`	Conflicto de estado: por ejemplo, un valor único repetido.
422	`validation_error`	El cuerpo o los parámetros no pasan la validación.
429	`too_many_requests`	Se pasó el límite. Reintenta más tarde.

Límites de uso

Los endpoints sensibles —sobre todo los de autenticación— van limitados por IP de origen y por cuenta, con ventana fija. Al pasarse, la API responde 429 con el envelope de siempre.

El límite es fail-open: si el servicio que los cuenta no está disponible, la petición NO se bloquea — prevalece la disponibilidad. Aun así, diseña tus clientes para reintentar con espera exponencial ante un 429, y evita las ráfagas que no hacen falta.