Erros

Todos os erros, em todos os endpoints, usam um único envelope:

{
  "error": {
    "code": "not_found",
    "message": "Link not found",
    "doc_url": "https://linkprofit.com/docs/api/errors"
  }
}

Ramifique conforme error.code e mostre error.message às pessoas. Os erros de validação acrescentam um array details com mensagens por campo:

{
  "error": {
    "code": "validation_failed",
    "message": "Request failed validation",
    "doc_url": "https://linkprofit.com/docs/api/errors",
    "details": [
      { "path": "url", "message": "Destination URL is not a valid address" }
    ]
  }
}

Códigos de erro

| Código | HTTP | Significado | O que fazer | |---|---|---|---| | unauthorized | 401 | Chave ausente, desconhecida, revogada ou expirada | Confira o cabeçalho; emita uma chave nova | | forbidden | 403 | Tipo de chave incorreto para o endpoint, ou operação não permitida | Use uma chave de espaço de trabalho ou de parceiro conforme a documentação | | insufficient_scope | 403 | Falta à chave um escopo obrigatório | Crie uma chave com o escopo indicado na mensagem | | plan_restricted | 403 | O plano não inclui essa capacidade | Faça upgrade do plano ou remova a funcionalidade da requisição | | not_found | 404 | O recurso não existe — ou pertence a outro tenant | Verifique o id; recursos alheios são indistinguíveis dos inexistentes | | invalid_request | 400 | JSON malformado, cursor inválido, regra de negócio violada | Corrija a requisição | | validation_failed | 422 | O corpo ou a query não passaram na validação do esquema | Corrija os campos listados em details | | conflict | 409 | Conflito de estado: slug ocupado, Idempotency-Key reutilizada com outro corpo | Escolha outro valor ou uma nova chave de idempotência | | quota_exceeded | 422 | Uma cota do plano se esgotou (links, domínios, clientes) | Faça upgrade do plano ou libere cota | | rate_limited | 429 | Requisições demais com essa chave | Espere os segundos de Retry-After; veja Limites de requisições | | not_configured | 503 | A capacidade não está configurada neste ambiente | Tente de novo mais tarde ou fale com o suporte | | internal | 500/502/504 | Erro inesperado da plataforma | Tente de novo com backoff; avise se persistir | | invalid_click_id | 422 | O click_id foi forjado, adulterado ou emitido em outro espaço de trabalho | Repasse o valor do parâmetro de identificador de clique exatamente como ele apareceu no endereço de destino | | attribution_expired | 422 | O clique é mais antigo que a janela de atribuição do espaço de trabalho | Não há o que repetir; ajuste a janela no painel se for necessário |

Regras de tratamento que compensam

• O 404 também é isolamento. Um id de outro espaço de trabalho responde not_found, nunca forbidden — a API não revela se um id alheio existe.
• Repita apenas o que for seguro. Faça novas tentativas de internal e rate_limited com backoff. Nunca repita às cegas conflict nem validation_failed — a própria requisição está errada. Use Idempotency-Key para tornar seguras as novas tentativas de mutação.
• GET /links nunca devolve 404. Filtros vazios devolvem uma lista vazia; um 404 na coleção seria ambíguo.