Entender é tratar os erros da API

A API pública CaptainDNS retorna todos os erros em um envelope JSON padronizado. Esta página lista os 10 códigos canonicos, seu significado é a ação corretiva recomendada.

Envelope padrao

Toda resposta de erro segue este formato:

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly credits quota reached for the current plan",
  "details": {
    "tier": "starter",
    "limit": 50000,
    "current": 50000
  },
  "request_id": "req_a1b2c3d4"
}

• code: string estavel. Use-a para ramificar sua logica de tratamento.
• message: descricao legivel em ingles. Não faca parse.
• details: objeto opcional com contexto especifico.
• request_id: identificador CaptainDNS, útil para abrir ticket de suporte.

Códigos de autenticação (401)

INVALID_API_KEY

Status: 401. Header Authorization ausente, prefixo ausente ou segredo alterado. Acao: verifique o header.

EXPIRED_API_KEY

Status: 401. A chave ultrapassou seu expires_at. Acao: crie uma nova chave.

REVOKED_API_KEY

Status: 401. A chave foi revogada. Acao: use a chave ativa.

Códigos de autorizacao (403)

INSUFFICIENT_SCOPE

Status: 403. A chave não carrega o escopo necessario.

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "Endpoint requires scope 'web:read'",
  "details": {
    "required": "web:read",
    "granted": ["dns:read", "mail:read"]
  }
}

Acao: crie uma chave com o escopo correto.

IP_NOT_ALLOWED

Status: 403. A chave tem uma allowlist de IP é o IP de origem não consta nela.

{
  "code": "IP_NOT_ALLOWED",
  "message": "Source IP not in the allowlist for this API key",
  "details": {
    "detected_ip": "203.0.113.42",
    "allowlist": ["4.175.114.0/23"]
  }
}

Acao: adicione seu IP a allowlist.

QUOTA_EXCEEDED

Status: 403. A cota mensal de créditos foi atingida é o plano não permite excedente.

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly credits quota reached",
  "details": {
    "tier": "free",
    "limit": 500,
    "current": 500,
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-05-01T00:00:00Z"
  }
}

Acao: espere o proximo período ou mude de plano.

Códigos de conflito (409)

IDEMPOTENCY_CONFLICT

Status: 409. Uma Idempotency-Key foi reutilizada com body diferente.

{
  "code": "IDEMPOTENCY_CONFLICT",
  "message": "Idempotency key reused with a different request body",
  "details": {
    "key": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Acao: gere uma nova chave.

Códigos de rate limit (429)

RATE_LIMITED

Status: 429. O token bucket por chave esta vazio ou o limite por IP foi ultrapassado.

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded",
  "details": {
    "scope": "per-key",
    "retry_after_seconds": 12
  }
}

O header Retry-After acompanha sempre este código.

Códigos de servidor (5xx)

INTERNAL_ERROR

Status: 500. Erro inesperado do lado CaptainDNS. Acao: guarde o request_id é abra um ticket.

SERVICE_UNAVAILABLE

Status: 503. Um subsistema necessario ao endpoint esta indisponivel.

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Public API is temporarily unavailable",
  "details": {
    "reason": "temporarily_unavailable"
  }
}

Acao: respeite o Retry-After.

Códigos de validacao (400)

A API também retorna 400 BAD_REQUEST para erros de validacao especificos de cada endpoint. Esses erros não seguem o envelope padrao.

Exemplo:

{
  "error": "invalid domain: must be a valid FQDN",
  "field": "domain"
}

Para os esquemas exatos, consulte a referência OpenAPI.

Tabela sintetica

Boas praticas de tratamento

• Ramifique no par (status, code): o status sozinho não basta.
• Registre o request_id: indispensavel para o suporte.
• Não reenvie cegamente: os 4xx exceto 429 indicam problema do cliente.
• Respeite Retry-After: 429 é 503 sempre o incluem.
• Alerte sobre taxas de erro: 1 % de 5xx em 5 minutos é um sinal de incidente.

Siga para a referência OpenAPI ou volte ao quickstart.