Errors

Every Swft error response uses the same envelope — RFC 9457 Problem Details compatible AND Stripe-shape, so any SDK that already groks Stripe-style envelopes can consume it unchanged.

{
  "error": {
    "type":       "https://docs.swft.co.uk/errors/idempotency_key_reused",
    "code":       "idempotency_key_reused",
    "message":    "Idempotency-Key was reused with a different request body.",
    "doc_url":    "https://docs.swft.co.uk/errors/idempotency_key_reused",
    "request_id": "req_01HZ9X...",
    "param":      "Idempotency-Key"
  }
}

request_id always echoes the value of the response swft-request-id header — paste it into support tickets.

Codes

HTTP	Code	Meaning
400	bad_request	Malformed input.
400	missing_parameter	A required parameter is missing. param names it.
400	invalid_parameter	A parameter failed validation. param names it.
400	missing_idempotency_key	Endpoint requires Idempotency-Key.
400	missing_swft_merchant_header	Endpoint requires X-Swft-Merchant.
400	unsupported_api_version	Swft-Version is not recognised. meta.supported lists valid versions.
401	missing_authorization	No Authorization: Bearer header.
401	invalid_api_key	Key not found or revoked.
403	forbidden	Authenticated but not authorised.
403	insufficient_scope	Key lacks a required scope. meta.required / meta.missing list them.
403	merchant_not_in_workspace	X-Swft-Merchant does not belong to the key’s workspace.
404	merchant_not_found	Merchant id unknown.
404	workspace_not_found	Workspace id unknown.
404	resource_not_found	Generic not-found.
404	webhook_delivery_not_found	Delivery id not in this workspace.
409	merchant_already_exists	store_url already registered.
409	idempotency_key_reused	Key reused with different body, or request still in-flight.
409	pre_confirmation_rejected	Partner pre-confirmation hook returned available:false. meta.reason repeats the partner-supplied reason.
409	custom_domain_already_set	Merchant already has a custom domain assigned.
429	rate_limited	Slow down. meta.retry_after is seconds.
503	pre_confirmation_unavailable	Partner endpoint timed out / 5xx’d and fail_mode=‘closed’.

Verification

The type URL is stable. Add it to your SDK’s switch statement without parsing the human-readable message. Each URL also serves as the documentation deeplink — link to it from your own error UI.