Conceitos

Erros

Todo erro segue a RFC 7807 com um code estável. Códigos publicados nunca mudam; códigos novos podem surgir, então trate o desconhecido pelo status HTTP.

Exemplo

{
  "type": "https://cuidaro.com.br/errors/settlement-amount-mismatch",
  "title": "Settlement Amount Mismatch",
  "status": 422,
  "detail": "settlement.amount é diferente do total da OS. Nada foi faturado.",
  "instance": "/api/v1/service-orders/731/invoice",
  "code": "SETTLEMENT_AMOUNT_MISMATCH",
  "expected_amount": "149.90",
  "received_amount": "149.00"
}

Em 422, chegam também errors (mensagens por campo) e error_codes (códigos por campo). detail é texto para pessoas e pode mudar. Erro 500 nunca traz mensagem interna.

Códigos e o que fazer

code	HTTP	O que significa	O que fazer
`AUTH_CREDENTIALS_INVALID`	401	`client_id`/`client_secret` errados ou integração revogada (emissão de token)	conferir as credenciais; se revogada ou segredo trocado, pedir as novas ao dono da empresa
`AUTH_TOKEN_EXPIRED`	401	token com mais de 1 h	pedir token novo em `POST /oauth/token` e repetir a chamada
`AUTH_TOKEN_MISSING`	401	faltou `Authorization: Bearer <token>`	enviar o cabeçalho
`AUTH_TOKEN_INVALID`	401	token desconhecido, segredo trocado ou integração revogada	pedir token novo; se continuar, a integração foi revogada ou o segredo trocado
`AUTH_SCOPE_INSUFFICIENT`	403	token sem o escopo da rota, ou `scope` pedido fora do permitido	pedir ao dono da empresa o escopo que falta (nova integração) ou pedir o token sem restringir `scope`
`AUTH_TENANT_SUSPENDED`	403	empresa bloqueada	a empresa precisa regularizar com o Cuidaro; não insistir
`AUTH_TENANT_PLAN_WITHOUT_API`	403	o plano da empresa não inclui API	a empresa precisa mudar de plano
`ACCESS_DENIED`	403	acesso negado (genérico)	não repetir; reportar se inesperado
`BAD_REQUEST`	400	requisição malformada (ex.: JSON inválido)	corrigir o corpo
`VALIDATION_FAILED`	422	dados inválidos	ler `errors`/`error_codes`, corrigir e reenviar com chave nova
`FIELD_REQUIRED`	422 (em `error_codes`)	campo obrigatório ausente	enviar o campo
`FIELD_TYPE_INVALID`	422 (em `error_codes`)	tipo de dado errado	corrigir o tipo
`FIELD_MAX_LENGTH`	422 (em `error_codes`)	valor maior que o permitido	encurtar
`FIELD_ENUM_INVALID`	422 (em `error_codes`)	valor fora da lista (ex.: `settlement.type`, escopo, evento)	usar um valor da lista do `openapi.json`
`FIELD_INVALID`	422 (em `error_codes`)	outra regra (ex.: documento inválido, IBGE de outra UF, serviço inativo)	ler a mensagem em `errors` e corrigir
`IDEMPOTENCY_KEY_MISSING`	422	`POST` sem `Idempotency-Key`	enviar a chave
`IDEMPOTENCY_KEY_INVALID`	422	chave fora do formato	1–255 caracteres ASCII visíveis, sem espaço
`IDEMPOTENCY_KEY_CONFLICT`	409	chave já usada com outro corpo	usar chave nova para a operação nova
`IDEMPOTENCY_KEY_IN_PROGRESS`	409	a mesma chave ainda está executando	comum: esperar alguns segundos e reenviar igual; estrita: consultar a OS e, se não aconteceu, chave nova
`RESOURCE_NOT_FOUND`	404	recurso inexistente ou de outra empresa (endpoint de webhook: também de outra integração), ou endereço errado	conferir o id e a URL
`METHOD_NOT_ALLOWED`	405	método HTTP não aceito no endereço	conferir o método na referência da API
`RESOURCE_STATE_CONFLICT`	409	operação inválida para o estado do recurso (OS já faturada/cancelada, OS sem valor a faturar, OS faturada pela tela no `cancel`, endpoint desativado, teto de 10 endpoints)	ler `detail` e `service_order_status`; consultar o recurso; não repetir igual
`PLAN_QUOTA_EXCEEDED`	409	limite do plano da empresa atingido (`metric`, `limit`)	a empresa precisa liberar espaço ou mudar de plano; depois, a mesma chave pode ser reenviada
`PAYLOAD_TOO_LARGE`	413	corpo acima de 512 KB	reduzir o corpo
`RATE_LIMIT_EXCEEDED`	429	limite de requisições por minuto excedido	esperar `Retry-After`; se for recorrente, pedir aumento ao suporte
`HTTP_ERROR`	o do erro	outro erro HTTP sem código específico	tratar pelo status; reportar se persistir
`INTERNAL_ERROR`	500	erro interno	tentar de novo depois (mesma chave); em operação estrita, consultar a OS antes; reportar se persistir
`SERVICE_UNAVAILABLE`	503	manutenção ou indisponibilidade temporária	tentar de novo em alguns minutos
`WEBHOOK_URL_NOT_ALLOWED`	422 (em `error_codes.url`)	URL de webhook não é `https://` público	usar `https://` que resolva só para IP público, sem usuário/senha e sem redirecionar
`RESOURCE_ALREADY_EXISTS`	409	`external_reference` já usada em outra OS, ou pagamento (`gateway` + `gateway_reference`) já usado em outra OS (`existing_resource_id`)	consultar a OS de `existing_resource_id`: normalmente é a sua própria criação anterior
`SETTLEMENT_AMOUNT_MISMATCH`	422	`settlement.amount` diferente do total da OS (`expected_amount`, `received_amount`)	conferir o valor; nada foi faturado
`EXTERNAL_SETTLEMENT_NOT_ALLOWED`	422	a empresa não liberou esta integração a informar pagamento recebido fora do Cuidaro (OS faturável)	pedir a liberação ao dono/administrador (Configurações → Integrações (API) → Pagamentos recebidos fora do Cuidaro)
`EXTERNAL_SETTLEMENT_ACCOUNT_MISSING`	422	liberada, mas sem conta ativa escolhida	pedir ao dono/administrador que escolha uma conta ativa

Referência gerada a partir do contrato OpenAPI 3.1 da API v1 (versão 2026-10-26), conferido contra o código por teste automatizado. Dúvidas: suporte@cuidaro.com.br.