Errors

Every machine-readable error code, its HTTP status, whether it is retryable, and what to do about it.

Every error response is RFC 9457 application/problem+json with a stable code. Switch on code, never on the human title or detail — codes are append-only and never change meaning; the texts may. The type URI of every code resolves to its row on this page.

The problem+json envelope

{
  "type": "https://pay.mmokick.com/developers/errors#rate_limited",
  "title": "Rate limited",
  "status": 429,
  "code": "rate_limited",
  "detail": "Write limit of 120 requests per minute exceeded.",
  "instance": "/api/v1/offers"
}

HTTP 400

code	Title	Retryable	What it means / what to do
`invalid_json`	Invalid JSON	no	The request body is not parseable JSON. Fix the request body.
`invalid_cursor`	Invalid cursor	no	The pagination cursor is unknown or expired. Restart the listing without a cursor.
`idempotency_key_invalid`	Invalid idempotency key	no	The `Idempotency-Key` header is empty or longer than 200 characters. Send a valid key.

HTTP 401

code	Title	Retryable	What it means / what to do
`unauthenticated`	Unauthenticated	no	The `Authorization` header is missing or malformed. Send `Authorization: Bearer <token>`.
`invalid_token`	Invalid token	no	The token is unknown. Check the token, or create a new one in the portal.
`token_revoked`	Token revoked	no	The token was revoked in the portal. Issue a new token.
`wrong_environment`	Wrong environment	no	A `ck_test_` token was used on production, or a `ck_live_` token on sandbox. Use the token that matches the host.

HTTP 403

code	Title	Retryable	What it means / what to do
`insufficient_scope`	Insufficient scope	no	The token lacks a scope the endpoint requires. Issue a token with the needed scope.
`supplier_suspended`	Supplier suspended	no	The supplier account is suspended by staff. Contact support.

HTTP 404

code	Title	Retryable	What it means / what to do
`not_found`	Not found	no	No such resource, or it does not belong to your supplier. Check the id.

HTTP 405

code	Title	Retryable	What it means / what to do
`method_not_allowed`	Method not allowed	no	The HTTP method is not allowed on this path. Fix the verb.

HTTP 409

code	Title	Retryable	What it means / what to do
`offer_exists`	Offer already exists	no	An offer already exists for this product. Update the existing offer instead of creating a second.
`invalid_state`	Invalid state	no	The requested transition is not allowed from the resource's current state. Read the current state first.
`stock_mode_mismatch`	Stock mode mismatch	no	An inventory operation was sent to a declared-stock offer, or a stock declaration to an uploaded offer. Use the operation that matches the offer's stock mode.
`idempotency_conflict`	Idempotency conflict	no	The `Idempotency-Key` was reused with a different request body. Use a new key.
`idempotency_in_flight`	Idempotency in flight	yes	The original request for this idempotency key is still running. Retry after the `Retry-After` interval.

HTTP 413

code	Title	Retryable	What it means / what to do
`payload_too_large`	Payload too large	no	The request body exceeds 1 MB. Split the batch into smaller requests.

HTTP 415

code	Title	Retryable	What it means / what to do
`unsupported_media_type`	Unsupported media type	no	The `Content-Type` is not `application/json`. Fix the header.

HTTP 422

code	Title	Retryable	What it means / what to do
`validation_failed`	Validation failed	no	One or more fields failed validation (see the `errors` map in the response). Fix the fields.
`product_not_sellable`	Product not sellable	no	The product is archived or paused for new offers. Pick another product.
`fulfilment_unreachable`	Fulfilment endpoint unreachable	yes	The inline healthcheck of your fulfilment endpoint failed on activation or URL change. Fix your endpoint, then retry.
`inventory_rejected`	Inventory rejected	no	A strict-mode upload contained invalid items (see `rejected_items`). Fix the items or upload in `partial` mode.

HTTP 429

code	Title	Retryable	What it means / what to do
`rate_limited`	Rate limited	yes	A rate limit was hit. Honor the `Retry-After` header and back off. See the rate limits page.

HTTP 500

code	Title	Retryable	What it means / what to do
`internal_error`	Internal error	yes	An error on our side, logged under the response `trace_id`. Retry with backoff; report it if it persists.

HTTP 503

code	Title	Retryable	What it means / what to do
`service_unavailable`	Service unavailable	yes	A maintenance window is in effect (carries `Retry-After`). Retry after the given interval.