Errors & Rate Limits | Documentação da API Mapalyze

Formato de erro

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

Códigos de erro

Código	HTTP	Significado
`missing_api_key`	401	Nenhuma chave API fornecida
`invalid_api_key`	401	Chave inválida/revogada/inativa
`invalid_api_key_environment`	401	Ambiente da chave (`live`/`test`) não habilitado neste gateway
`forbidden`	403	Escopo insuficiente para o endpoint
`tier_required`	403	Recurso da API requer o plano Team
`not_found`	404	Endpoint ou recurso não encontrado
`validation_error`	400	Body, parâmetros, geometria ou IDs inválidos
`idempotency_key_conflict`	409	Mesmo `Idempotency-Key` usado com payload diferente
`idempotency_in_progress`	409	Requisição com mesmo `Idempotency-Key` ainda em processamento
`rate_limit_exceeded`	429	Limite por minuto (ou cota diária do plano) excedido
`timeout`	504	Exportação expirou
`usage_service_unavailable`	503	Serviço de uso/cota indisponível
`tier_check_unavailable`	503	Serviço de validação de plano indisponível
`internal_error`	500	Erro inesperado do servidor

Códigos de status HTTP utilizados

Status	Significado
200	Sucesso
201	Criado
204	Excluído sem corpo
400	Erro de validação
401	Não autorizado
403	Proibido
404	Não encontrado
409	Conflito/em andamento de idempotência
429	Limite de taxa excedido
500	Erro interno
503	Serviço upstream indisponível
504	Timeout

Limites de taxa

Limite por minuto por chave

Cada chave tem um limite por minuto (padrão 300 req/min, configurável por chave).

Exemplo de resposta 429:

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

Cota diária do plano

Além dos limites por minuto, uma cota diária no nível do plano se aplica. Se atingida, a API retorna 429 com uma indicação de retentativa de 24h.

Comportamento de idempotência

Para rotas de escrita usando POST e PUT:

Mesmo Idempotency-Key + mesmo payload: resposta em cache reproduzida
Mesma chave + payload diferente: 409 idempotency_key_conflict
Mesma chave enquanto a primeira requisição ainda está em processamento: 409 idempotency_in_progress

Respostas reproduzidas incluem:

Idempotency-Replayed: true

Endpoints de administração

GET /v1/organization

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

GET /v1/webhooks (escopo admin)

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

Painel de operações API (escopo 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