Errors

Every error from the API has the same format (RFC 9457, content type application/problem+json). This is true for all errors: wrong key, unknown path, bad input, too many requests and problems on our side.

{
  "type": "https://docs.smartchat.marketing/en/errors#insufficient_scope",
  "title": "Missing permission",
  "status": 403,
  "error_type": "permission",
  "code": "insufficient_scope",
  "message": "This key lacks the permission 'contacts:write'.",
  "param": null,
  "retryable": false,
  "doc_url": "https://docs.smartchat.marketing/en/errors#insufficient_scope",
  "request_id": "req_01JAB9C3X7K2M4N5P6Q7R8S9T0",
  "required_scope": "contacts:write"
}

#Fields

Name	Type	Required	Description
`type`	string	yes	URL of the documentation for this error. up to 300 characters
`title`	string	yes	Short title. up to 100 characters
`status`	integer	yes	HTTP status. 400 to 599
`error_type`	string	yes	Stable error class. Branch on this first, then on code. one of: `authentication`, `permission`, `invalid_request`, `conflict`, `rate_limit`, `api`
`instance`	string	no	Path of the request that failed. up to 300 characters
`code`	string	yes	Stable error code from the error catalog. up to 60 characters
`message`	string	yes	English explanation. Contains no personal data. up to 500 characters
`param`	string or null	no	Path of the invalid field, for example body.tags[2]. up to 200 characters
`retryable`	boolean	yes	True if the same request may work later.
`doc_url`	string	yes	Link to the error page. up to 300 characters
`request_id`	string	yes	ID of the request, also in the Request-Id header. up to 40 characters
`errors`	array of object	no	All input errors when more than one field is invalid. up to 50 items
`errors[].param`	string	yes	Path of the field. up to 200 characters
`errors[].code`	string	yes	Error code. up to 60 characters
`errors[].message`	string	yes	English explanation. up to 500 characters

Some errors add fields that belong to them, for example required_scope, existing_id or limit. Their meaning is explained under the code in the error catalog.

#How to handle an error

Look at error_type first. It is one of authentication, permission, invalid_request, conflict, rate_limit or api. It never changes for a code.
Then look at code. Codes are stable. The message is for people; do not parse it.
If retryable is true, the same request may work later. For rate_limited wait for the seconds in Retry-After. Otherwise change the request.
Keep the request_id. If you need help, write to support and include it.

#400 and 422

400: the request is not built correctly. For example the body is not JSON, a field is missing or unknown, or the cursor is broken.
422: the request is built correctly, but its content breaks a rule. For example a phone number is not valid, or the contact has no opt-in.

#Several wrong fields

If more than one field is wrong, errors lists all of them in one answer, each with param, code and message. The param is the path of the field, for example body.tags[2].

#Never an error you cannot trace

Error messages contain no personal data. If a connected service such as WhatsApp reports a problem, you get upstream_error with a short code, never the raw text of the other service.