Errors

An error answers with an HTTP status in the 4xx or 5xx range and a body in the Problem Details format (RFC 7807), served as application/problem+json.

{
  "type": "https://developers.offmy.co/errors/missing_scope",
  "title": "Missing scope",
  "status": 403,
  "detail": "This API key does not have the required scope.",
  "instance": "/v1/orders?limit=50",
  "required_scope": "read:orders"
}

Some errors add members of their own (required_scope, supported_versions, errors…), described with each error below. Ignore the members you do not know.

Resources outside the reach of your key (another agency, or a creator the key does not cover) answer 404, exactly like resources that do not exist.

Every response, error or not, carries an x-request-id header. It repeats the x-request-id of your request when you send one. Quote it when you contact support.

Authentication

missing_authorization

401. No Authorization: Bearer … header. Send your API key, see Authentication.

invalid_api_key

401. The key is malformed, unknown or revoked. Check that the full key was copied, then create a new one if it was revoked.

expired_api_key

401. The key passed the expiration date chosen at its creation. Create a new key.

missing_scope

403. The key does not have the scope this endpoint needs, given in required_scope. Create a key with that scope.

ip_not_allowed

403. Reserved for per-key IP allowlists. Not returned today.

Version

missing_version

400. The Fansquare-Version header is missing. The error gives current_version, current_version_date and a ready header in example. See Versioning.

unknown_version

400. The Fansquare-Version value is not a released version. supported_versions lists the valid ones.

Request

validation_failed

400. A parameter or the body is invalid: wrong type, value out of range, unknown query parameter on an endpoint that takes query parameters, inconsistent date range, or a body that is not valid JSON.

When the request does not match the schema of the endpoint, errors lists each problem. Read two members of each item:

• path: where the problem is, in the query or the body, with dots between levels (limit, enabled_event_types.0). It is empty when the problem concerns the whole query or body, such as an unknown parameter.

• message: what is wrong.

The items also carry keyword, instancePath, schemaPath and params, the raw output of the validator: do not rely on them. The other validation_failed errors, such as an inconsistent date range or a body that is not valid JSON, have no errors: detail explains the problem.

payload_too_large

413. The request body is over 256 KB. Send less data per request.

unsupported_media_type

415. The body is not sent as JSON. Set Content-Type: application/json. An empty body with that header is accepted on endpoints that take no body.

invalid_cursor

400. The cursor was altered or was not issued by the API. Read it from the previous page, see Pagination.

precondition_required

428. Editing a fan note requires the concurrency token read with it, in the etag body field or the If-Match header. See Update the insight note of a fan.

precondition_failed

412. The fan note changed since you read it. When the current token is known, it is in current_etag: retry with it, or read the note again and retry with the fresh token.

Not found

not_found

404. No endpoint at this path. Check the method and the path, including the /v1 prefix. The version header and the API key are checked first: without them, an unknown path answers 400 or 401, not 404.

unknown_account

404. No connected MYM account with this account_id within the reach of your key. Take the id from account.external_id in List creators.

unknown_fan

404. No fan with this fan_id on this account.

unknown_order

404. No order with this id within the reach of your key.

unknown_creator

404. No creator with this id within the reach of your key.

unknown_user

422. The employee given in the body is not a member of the agency. List them with List employees.

unknown_tag

422. One or more tag ids do not match a tag of the agency. They are listed in tag_ids; the catalogue comes from List tags.

unknown_publication

404. No publication with this id within the reach of your key.

unknown_webhook_endpoint

404. No webhook endpoint with this id within the reach of your key. A key limited to some creators only reaches the endpoints that cover its own creators and no other.

unknown_webhook_failure

404. No failed delivery with this id on this endpoint. Failures are kept 30 days.

Webhooks

undeliverable_url

422. The endpoint URL must use HTTPS and point to a public host: no localhost, private network ranges, .internal or .local names.

webhook_endpoint_limit

422. The agency already has 10 webhook endpoints, the maximum. Delete one first.

webhook_endpoint_disabled

409. The endpoint is disabled, by you or after repeated failures. Re-enable it with status: "active" before sending a test delivery.

Limits and availability

rate_limited

429. Too many requests for this key. Wait the number of seconds given in the Retry-After header. See Rate limits.

internal_error

500. An error on our side. The body carries a request_id, the value of the x-request-id header: give it to support if the error persists.

unavailable

503. A service the request depends on is temporarily unavailable. Retry after a short delay.

Retry a request

A 429, a 5xx or a timeout can be retried. Before you retry a write, check what a repeat does:

• PUT and DELETE can be repeated: the result is the same. A DELETE repeated on a publication or a webhook endpoint answers 404, the resource being already gone.

• POST /v1/publications and POST /v1/webhooks create a new resource on every call. After a timeout, list the resources first: a blind retry can create a duplicate.

The API does not support an Idempotency-Key header.