Guides

Errors

How an error is written, and every code the API answers with.

An error comes back as application/problem+json with a code that stays the same from one release to the next. Test for the code, not the wording of the message, which may be improved at any time.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://www.footer365.com/help/technical/api#errors",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key does not hold the rules.write scope. That needs an organisation's key, made on Developers > API keys in the customer portal, with the scope ticked.",
  "code": "scope_missing"
}

A change that cannot be made in full is not made at all. Where several fields were refused, errors names each one with the reason beside it.

Status Code Meaning
400 https_required, key_in_query, no_fields, invalid_limit, invalid_cursor, invalid_query, no_entries, no_usable_entries, list_too_large The request itself is wrong.
401 missing_key, invalid_key, key_revoked, key_expired, address_not_allowed, account_closed, account_inactive, api_not_available The key was not accepted. api_not_available means the public API is not available to your organisation at the moment; the key is kept and works again once it is.
403 scope_missing, folder_read_only, rule_outside_scope, campaign_outside_scope, list_organisation_wide, reseller_key_required, not_available The key does not hold the scope the call needs, which the message names, may not change what is in that folder, or was made by an administrator limited to part of the organisation and the rule or campaign is aimed beyond it, or the call changes a recipient list, which belongs to the whole organisation. not_available means that part of the API, such as campaigns or recipient lists, is not available to your organisation at the moment; nothing it set up is lost.
404 user_not_found, no_signature, template_not_found, rule_not_found, campaign_not_found, recipient_list_not_found, customer_not_found Nothing to return. Something the key may not reach is not found, rather than refused, so its existence is not given away.
409 campaign_not_running, campaign_not_paused, list_not_changed The campaign is not in a status the call can be made from, or the recipient list could not be changed just now, for example because it is being imported; the list is left as it was.
422 fields_refused, campaign_refused A change could not be made; see errors or the message.
429 rate_limited Too many calls; wait for Retry-After seconds. See rate limits.
500 save_failed A change could not be saved, so nothing was changed. Try again.
503 keys_unavailable Keys cannot be checked at the moment. Try again in a few minutes.

Every answer, an error or not, carries an X-Request-Id. Quote it if you contact support about a call.