Errores y Límites de Tasa

Formato de error

{
  "ok": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}

Códigos de error

Código	HTTP	Significado
`missing_api_key`	401	No se proporcionó clave API
`invalid_api_key`	401	Clave inválida/revocada/inactiva
`invalid_api_key_environment`	401	Entorno de clave (`live`/`test`) no habilitado en este gateway
`forbidden`	403	Alcance insuficiente para el endpoint
`tier_required`	403	La función API requiere el plan Team
`not_found`	404	Endpoint o recurso no encontrado
`validation_error`	400	Cuerpo, parámetros, geometría o IDs inválidos
`idempotency_key_conflict`	409	Mismo `Idempotency-Key` usado con payload diferente
`idempotency_in_progress`	409	Solicitud con mismo `Idempotency-Key` aún en proceso
`rate_limit_exceeded`	429	Límite por minuto (o cuota diaria del plan) excedido
`timeout`	504	Exportación agotó el tiempo
`usage_service_unavailable`	503	Servicio de uso/cuota no disponible
`tier_check_unavailable`	503	Servicio de validación de plan no disponible
`internal_error`	500	Error inesperado del servidor

Códigos de estado HTTP utilizados

Estado	Significado
200	Éxito
201	Creado
204	Eliminado sin cuerpo
400	Error de validación
401	No autorizado
403	Prohibido
404	No encontrado
409	Conflicto/en progreso de idempotencia
429	Límite de tasa excedido
500	Error interno
503	Servicio upstream no disponible
504	Timeout

Límites de tasa

Límite por minuto por clave

Cada clave tiene un límite por minuto (por defecto 300 req/min, configurable por clave).

Ejemplo de respuesta 429:

{
  "ok": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit of 300 requests/minute exceeded. Retry after 27 seconds.",
    "retry_after": 27
  }
}

Cuota diaria del plan

Además de los límites por minuto, se aplica una cuota diaria a nivel de plan. Si se alcanza, la API devuelve 429 con una indicación de reintento de 24h.

Comportamiento de idempotencia

Para rutas de escritura usando POST y PUT:

Mismo Idempotency-Key + mismo payload: respuesta en caché reproducida
Misma clave + payload diferente: 409 idempotency_key_conflict
Misma clave mientras la primera solicitud aún se procesa: 409 idempotency_in_progress

Las respuestas reproducidas incluyen:

Idempotency-Replayed: true

Endpoints de administración

GET /v1/organization

curl -H "X-API-Key: mk_live_..." \
  "https://<ref>.supabase.co/functions/v1/api-gateway/v1/organization"

GET /v1/webhooks (alcance admin)

curl -H "X-API-Key: mk_live_..." \
  "https://<ref>.supabase.co/functions/v1/api-gateway/v1/webhooks"

Panel de operaciones API (alcance admin)

GET /v1/api/metrics
GET /v1/api/reliability
GET /v1/api/alerts
POST /v1/api/alerts/run
POST /v1/api/alerts/:id/ack
GET /v1/api/key-lifecycle-alerts
POST /v1/api/key-lifecycle-alerts/run
POST /v1/api/key-lifecycle-alerts/:id/ack