Errors
When a call fails, the answer is a problem: a JSON body sent as application/problem+json, with a code.
Branch on code. The title and detail are for people to read.
If you contact support, quote the request_id. It is also sent as the Request-Id header on every answer, failed or not.
The shape of a problem
| Field | Type | Always there | What it is |
|---|---|---|---|
type | string | yes | A page on the documentation site for this code: https://matrixrewards.co.uk/docs/errors/<code>. |
title | string | yes | A short summary of the code, for people. Branch on code, not on this. |
status | integer | yes | The HTTP status of the answer, repeated in the body. |
code | string | yes | What went wrong, as a word a program can branch on. One of invalid_request, invalid_cursor, unauthenticated, forbidden_scope, not_found, unsupported_version, rate_limited, internal, access_not_recorded, payload_too_large, idempotency_key_reused, idempotency_key_in_use, confirmation_required, confirmation_invalid, test_mode_key, credit_limit_reached, member_has_no_store, code_already_used, store_not_connected, upstream_failed, change_not_recorded, forbidden_for_assistant, webhook_limit_reached, settings_changed, retroactive_change, programme_write_limit, last_reward, offer_read_only, offer_ended, programme_not_set_up, assistant_limit, invalid_image, too_many_images, shopify_file_unavailable, previous_secret. |
detail | string | no | What happened, in a sentence for people. |
instance | string | no | The path that was called. |
param | string | no | The field, header or query parameter at fault, when there is exactly one. |
request_id | string | yes | This request's id, also sent as the Request-Id header. Quote it if you contact support. |
doc_url | string | yes | The same page as type: this code's page on the documentation site. |
bucket | one of read, write | no | With rate_limited: which allowance ran out, reads or writes. |
required_scope | one of the Scope values | no | With forbidden_scope: the scope this call needs, which the key does not hold. |
key_scopes | list of Scope values | no | With forbidden_scope: every scope this key holds. |
supported_versions | list of string | no | With unsupported_version: the versions this platform serves. |
max_bytes | integer | no | With payload_too_large: the largest body accepted, in bytes. |
max_points | integer | no | With invalid_request on delta_points: the largest change allowed, either way. |
max_chars | integer | no | With invalid_request on reason: the longest reason allowed. |
max_endpoints | integer | no | With webhook_limit_reached: how many enabled endpoints an account may have. |
reason | string | no | With confirmation_invalid: expired (preview again), wrong_request (the key, member, body or Idempotency-Key differ from the preview) or malformed (not a confirmation this API issued). With invalid_request on a webhook url: what is wrong with the address, as listed under WebhookEndpointRequest. One of malformed, expired, wrong_request, not_a_url, too_long, not_https, port_not_allowed, has_credentials, has_fragment, blocked_name, own_host, blocked_address, does_not_resolve. |
direction | one of credit, debit | no | With credit_limit_reached: credit for points added, debit for points taken away. |
limit_points | integer | no | With credit_limit_reached: the account's limit in this direction. |
used_points | integer | no | With credit_limit_reached: what the account has already moved in this direction in the window. |
upstream_reason | string | no | With upstream_failed: why Shopify's answer did not confirm the code was switched off. |
problem | string | no | With invalid_request or retroactive_change from a programme change: the platform's own reason, like campaign_starts_in_past or retroactive_start. With assistant_limit, which limit: point_value_locked, currency_locked, expiry_locked, more_than_double, raised_from_zero, earning_more_than_double, everyday_rate_moved, changes_how_it_pays, changes_who_it_pays, changes_what_it_gives, minimum_more_than_halved, new_offer_kind, new_reward_too_generous or new_reward_kind. |
current_effective_from | string, or null | no | With retroactive_change: when the expiry rule shoppers were told about took effect, or null when there is none. |
current_period_months | integer, or null | no | With retroactive_change: that rule's period in months, or null when there is none. |
before | number or string or boolean, or null | no | With assistant_limit: the figure at the assistant's starting point, in the unit of param (a rate, points, an amount, a percentage, a kind; true or false for whether referrals run). |
asked | number or string or boolean, or null | no | With assistant_limit: what the change asked for, in the same unit. |
most_allowed | number or string or boolean, or null | no | With assistant_limit, when the figure was raised: the most it may rise to. Null where no value of it would do. |
least_allowed | number or string or boolean, or null | no | With assistant_limit, when a cost or a smallest order was lowered, or the everyday rate lowered while an offer rose: the least it may fall to. Null where no value of it would do. |
limit | integer | no | With programme_write_limit: how many programme changes the account may make through the API in the window. |
used | integer | no | With programme_write_limit: how many it has made in the window. |
Every code
| Code | Status | What it is | Safe to send again? |
|---|---|---|---|
invalid_request | 400 | The request could not be understood | Fix it first |
invalid_cursor | 400 | The cursor is not one this endpoint issued | Fix it first |
unauthenticated | 401 | No usable API key was presented | Fix it first |
forbidden_scope | 403 | This key does not carry the scope this call needs | Fix it first |
not_found | 404 | No such resource | Fix it first |
unsupported_version | 404 | That API version is not served here | Fix it first |
rate_limited | 429 | Too many requests for this key | Yes, after waiting |
internal | 500 | Something went wrong at our end | Yes, unchanged |
access_not_recorded | 503 | The access could not be recorded, so the data was not returned | Yes, unchanged |
payload_too_large | 413 | The request body is larger than this endpoint accepts | Fix it first |
idempotency_key_reused | 422 | This Idempotency-Key was already used for a different request | Fix it first |
idempotency_key_in_use | 409 | A request with this Idempotency-Key is still being processed | Yes, after waiting |
confirmation_required | 428 | This key must preview the change and send back its confirmation | Fix it first |
confirmation_invalid | 428 | The confirmation does not match this request, or has expired | Fix it first |
test_mode_key | 403 | A test key can preview a change but never make one | No |
credit_limit_reached | 409 | The daily limit for points changed through the API has been reached | No |
member_has_no_store | 409 | This member is not linked to a store the change could be booked to | No |
code_already_used | 409 | The code has already been spent at checkout | No |
store_not_connected | 503 | The store this code belongs to is not connected | Fix it first |
upstream_failed | 502 | Shopify did not confirm the code was switched off, so nothing was changed | Yes, unchanged |
change_not_recorded | 503 | The change could not be recorded, so it was not made | Yes, unchanged |
forbidden_for_assistant | 403 | A key for an assistant cannot manage webhooks | No |
webhook_limit_reached | 409 | This account already has as many webhook endpoints as it may | Fix it first |
settings_changed | 409 | The programme changed after it was read, so nothing was changed | Fix it first |
retroactive_change | 422 | The expiry change would reach back before shoppers were told | Fix it first |
programme_write_limit | 429 | The daily limit for programme changes through the API has been reached | No |
last_reward | 409 | The store's only reward cannot be removed | Fix it first |
offer_read_only | 409 | This rule is not one the API changes | No |
offer_ended | 409 | The campaign has ended, so it can only be removed | No |
programme_not_set_up | 409 | This store has no programme set up yet | Fix it first |
assistant_limit | 403 | An assistant's key cannot make a change this large | Fix it first |
invalid_image | 422 | The picture is not one a store can use | Fix it first |
too_many_images | 409 | The store already keeps as many pictures as it may | Fix it first |
shopify_file_unavailable | 502 | Shopify did not send the picture | Yes, unchanged |
previous_secret | 403 | A key's previous secret cannot create a webhook endpoint | Fix it first |