Errors
Errors follow RFC 9457 (problem details), with Content-Type: application/problem+json:
{ "type": "https://atende.suporteja.com.br/developers/errors#insufficient_scope", "title": "Insufficient permission",
"status": 403, "code": "insufficient_scope", "detail": "This key does not have the permission crm:write.",
"required_scopes": ["crm:write"], "request_id": "9f1c…" }
Always use the code field (stable); title and detail follow the account language or Accept-Language (pt-BR,
en). Every response carries X-Request-Id; give it to support.
| Status | code |
When |
|---|---|---|
| 400 | invalid_request, credentials_in_url, invalid_json |
Malformed request; key in the URL; body is not JSON |
| 401 | invalid_api_key, api_key_expired, api_key_revoked |
See authentication |
| 403 | insufficient_scope (+ required_scopes), forbidden, ip_not_allowed, plan_required (+ plan), account_suspended, approvals_unavailable |
Scope, role, IP, plan |
| 404 | not_found |
Not in this account (other accounts' ids are 404 too) |
| 409 | duplicate_contact (+ existing_id), idempotency_conflict |
Contact exists; idempotency key reused |
| 413 | payload_too_large |
Body over 256 KB |
| 422 | invalid_parameter (+ parameter), validation_failed (+ errors), invalid_cursor, messaging_window_closed, CRM rules (lost_reason_required, deal_closed, …) |
Parameters and rules |
| 429 | rate_limited, send_limit_reached (+ Retry-After) |
Usage limits |
| 500 / 503 | internal_error / unavailable |
Our error / API temporarily off |
Unknown parameters are 422 invalid_parameter too: send only what is documented.