Erros
Os erros seguem a RFC 9457 (problem details), com Content-Type: application/problem+json:
{ "type": "https://atende.suporteja.com.br/developers/errors#insufficient_scope", "title": "Permissão insuficiente",
"status": 403, "code": "insufficient_scope", "detail": "Esta chave não tem a permissão crm:write.",
"required_scopes": ["crm:write"], "request_id": "9f1c…" }
Use sempre o campo code (estável); title e detail vêm no idioma da conta ou do Accept-Language (pt-BR, en).
Toda resposta tem X-Request-Id; informe-o ao suporte.
| Status | code |
Quando |
|---|---|---|
| 400 | invalid_request, credentials_in_url, invalid_json |
Requisição malformada; chave na URL; corpo não é JSON |
| 401 | invalid_api_key, api_key_expired, api_key_revoked |
Ver autenticação |
| 403 | insufficient_scope (+ required_scopes), forbidden, ip_not_allowed, plan_required (+ plan), account_suspended, approvals_unavailable |
Permissão, papel, IP, plano |
| 404 | not_found |
Não existe nesta conta (ids de outras contas também são 404) |
| 409 | duplicate_contact (+ existing_id), idempotency_conflict |
Contato já existe; chave de idempotência reutilizada |
| 413 | payload_too_large |
Corpo acima de 256 KB |
| 422 | invalid_parameter (+ parameter), validation_failed (+ errors), invalid_cursor, messaging_window_closed, regras do CRM (lost_reason_required, deal_closed, …) |
Parâmetros e regras |
| 429 | rate_limited, send_limit_reached (+ Retry-After) |
Limites de uso |
| 500 / 503 | internal_error / unavailable |
Erro nosso / API desligada temporariamente |
Parâmetros desconhecidos também são 422 invalid_parameter: envie só o que está documentado.