Erros

Todo erro da API do Festero é uma resposta application/problem+json (RFC 9457). O campo code é um contrato estável: decida pelo code, nunca pelo title nem pelo detail. Ao pedir ajuda ao suporte, envie o requestId da chamada.

Formato

{
  "type": "https://developers.festero.com.br/errors#scope_missing",
  "title": "Forbidden",
  "status": 403,
  "detail": "This credential lacks the 'quotes:read' scope required by this resource.",
  "code": "scope_missing",
  "requestId": "6f1c2a9e-0b7d-4c1e-9a52-3e8f7d1c0a44"
}

Campo	Significado
type	Endereço desta página com a âncora do código, por exemplo https://developers.festero.com.br/errors#scope_missing.
title	Nome curto do status HTTP, em inglês (Forbidden, Not Found). Não use para decidir nada.
status	O status HTTP da resposta.
detail	Explicação em inglês para quem lê o log. O texto pode mudar sem aviso.
code	O código do erro, estável. É ele que o seu código deve tratar.
requestId	Identificador da chamada. Envie ao suporte ao perguntar sobre uma resposta.
errors	Só em validation_failed: a lista de campos inválidos, cada item com field e message.

Resumo dos códigos

Código	HTTP	Repetir a chamada?
validation_failed	400	Não, corrija a requisição
token_invalid	401	Não, corrija o cabeçalho ou o token
token_expired	403	Sim, com um token novo
credential_revoked	401 ou 403	Não, é preciso uma credencial nova
plan_required	403	Não, depende do plano da empresa
access_denied	403	Não, fale com o suporte
scope_missing	403	Não, falta o escopo na credencial
method_not_allowed	403	Não, confira o caminho
not_found	404	Não, confira o id
rate_limited	429	Sim, depois de esperar o Retry-After
internal_error	500	Sim, com espera crescente
gateway_error	5xx	Sim, com espera crescente
maintenance	503	Sim, depois da janela

validation_failed

HTTP 400. Algum parâmetro de consulta é inválido: cursor malformado, limit fora de 1 a 100, status desconhecido ou data fora do formato yyyy-MM-dd. O campo errors lista cada campo com problema.

O que fazer: corrija a requisição. Repetir a mesma chamada falha do mesmo jeito. Veja os formatos aceitos em Paginação e datas.

token_invalid

HTTP 401. O cabeçalho Authorization está ausente ou malformado, ou a assinatura do token não é válida.

O que fazer: envie Authorization: Bearer <access_token> com um token emitido pelo endpoint de token do Festero. Veja Autenticação.

token_expired

HTTP 403. O token de acesso passou dos 60 minutos de validade.

O que fazer: peça um novo token e guarde-o durante toda a validade. Não peça um token a cada chamada: o endpoint de token tem limite de uso.

credential_revoked

HTTP 401 ou 403. A credencial foi revogada, suspensa ou expirou no Festero, ou ainda está Ativando (acabou de ser criada).

O que fazer: se a credencial acabou de ser criada, espere o status passar a Ativa em API do Festero. Nos outros casos, peça ao administrador da empresa uma credencial nova. Repetir a chamada não resolve.

plan_required

HTTP 403. O plano da empresa não inclui a API. Os planos Premium e Enterprise incluem.

O que fazer: a empresa precisa mudar de plano no Festero. Não repita a chamada.

access_denied

HTTP 403. A chamada foi recusada por um motivo que não pode ser divulgado.

O que fazer: confira a credencial em API do Festero e fale com o suporte informando o requestId.

scope_missing

HTTP 403. A credencial não tem o escopo do conjunto de dados que a rota lê. O campo detail informa qual escopo falta.

O que fazer: crie uma credencial que inclua esse conjunto de dados em API do Festero; os escopos de uma credencial existente não mudam. Veja os escopos em Autenticação.

method_not_allowed

HTTP 403. O método ou o caminho não existe nesta API. A API é somente de leitura.

O que fazer: confira o caminho e o método na Referência interativa.

not_found

HTTP 404. O recurso não existe ou não está visível para esta credencial, o que inclui recursos de outra empresa.

O que fazer: confira o id. Um recurso excluído no Festero deixa de aparecer.

rate_limited

HTTP 429. O limite do plano por minuto ou a cota do dia foi atingido. A resposta traz o cabeçalho Retry-After (60 segundos), e o detail diz qual dos dois estourou.

O que fazer: espere o tempo do Retry-After e diminua o ritmo. Prefira sales-summary e updatedSince a paginar tudo. Veja Limites de uso.

internal_error

HTTP 500. Erro inesperado do nosso lado.

O que fazer: tente de novo com espera crescente. Se persistir, fale com o suporte informando o requestId.

gateway_error

HTTP 5xx do gateway (por exemplo, 504 quando a API leva mais de 29 segundos para responder). A API ficou indisponível ou passou do tempo limite.

O que fazer: tente de novo com espera crescente. Se repetir, reduza a consulta (limit menor, período mais curto).

maintenance

HTTP 503. Código reservado para janelas de manutenção anunciadas. Nenhuma resposta atual da API usa este código.

O que fazer: se um dia aparecer, tente de novo depois da janela.

Webhooks

O contrato de entrega dos webhooks (cabeçalhos, assinatura, reentregas e limites) está em Webhooks e em Verificar a assinatura.