Erros#

Todo erro da API responde em application/problem+json (RFC 9457):

{
  "type": "https://api.guruagenda.com.br/docs/errors#slot_unavailable",
  "title": "Horário indisponível",
  "status": 409,
  "code": "slot_unavailable",
  "detail": "Nenhum profissional livre neste horário.",
  "errors": [],
  "request_id": "req_01JABCDEF0123456789XYZ"
}

• code é estável e em inglês. É por ele que a sua integração decide o que fazer.
• title e detail são texto para pessoas, em português, e podem mudar.
• errors lista os campos com problema (field, code, message) nos erros de validação.
• request_id identifica a requisição. Informe-o ao suporte.
• type aponta para o código nesta página.

Erros 4xx não melhoram com uma nova tentativa igual: corrija o pedido. Só 429, 500 e 503 valem ser repetidos, esperando um pouco entre as tentativas.

Autenticação e acesso#

unauthorized#

401. A chave não veio, está errada, foi revogada ou expirou. Confira o header Authorization: Bearer ga_live_…. Muitas tentativas com chave inválida bloqueiam o IP por 30 minutos.

forbidden_scope#

403. A chave não tem o escopo que a rota exige (read, write ou webhooks:manage). Peça ao dono da conta uma chave com o escopo.

feature_not_enabled#

403. O plano da organização não inclui a API, ou a rota depende de uma funcionalidade desligada (por exemplo, a Fila Online).

forbidden_overbook#

403. O agendamento pediu encaixe (allow_overbook: true) num horário ocupado, e a organização não permite encaixe.

Pedido inválido#

validation_error#

400. Um parâmetro ou campo do corpo é inválido: tipo errado, valor fora da lista, data mal formada, URL de webhook recusada. errors[] diz qual campo e por quê.

client_identifier_required#

422. A organização exige telefone, e-mail ou CPF para cadastrar clientes, e o pedido não trouxe o que falta. errors[] diz quais campos.

template_invalid#

422. O template de um webhook não compila ou usa algo que não é permitido. errors[] aponta o campo do template.

Não encontrado#

not_found#

404. O recurso não existe nesta organização. Recurso de outra organização também responde 404.

Conflitos#

slot_unavailable#

409. O horário não está livre: outro agendamento, bloqueio, fora do expediente ou sem profissional disponível. Consulte /v1/availability/slots e tente outro horário.

min_advance_violation#

409. O horário pedido não respeita a antecedência mínima da organização, ou já passou.

professional_cannot_perform_service#

409. O profissional indicado não executa um dos serviços pedidos.

appointment_not_editable#

409. O status do agendamento não permite a ação (por exemplo, confirmar um agendamento cancelado) ou ele já tem nota fiscal emitida.

action_not_allowed#

409. A ação não é permitida para este agendamento por uma regra da organização. O detail explica qual.

queue_closed#

409. A Fila Online do profissional (ou de todos) está fechada agora.

deposit_required#

409. O serviço exige sinal, que só pode ser pago pela página pública de agendamento. Entradas com sinal não são criadas pela API.

queue_entry_not_editable#

409. O status da entrada na fila não permite a ação (por exemplo, chamar alguém que já foi atendido).

duplicate_request#

409. A Idempotency-Key já foi usada nas últimas 24 horas com um corpo diferente. Gere uma chave nova para cada operação.

webhook_limit_reached#

409. A organização já tem o máximo de webhooks (20). Remova um antes de criar outro.

webhook_inactive#

409. O webhook está desativado. Reative-o (active: true) antes de testar.

Limites e indisponibilidade#

rate_limited#

429. Limite de requisições estourado. Espere os segundos do header Retry-After e tente de novo.

internal_error#

500. Erro do nosso lado. Pode tentar de novo em instantes; se persistir, fale com o suporte informando o request_id.

api_disabled#

503. A API foi desligada temporariamente por manutenção ou incidente. Tente de novo mais tarde.

method_not_allowed#

405. O método HTTP não existe para esta rota (por exemplo, DELETE num agendamento). Veja a referência.