Error catalogue

All API errors return a JSON body:

{
  "error": "order_not_found",
  "message": "Human-readable description.",
  "request_id": "req_01j2…"
}

Always log request_id — it maps directly to CloudWatch traces and is required for support escalations.

HTTP 400 — Bad Request

error	Cause	Remediation
invalid_request	Missing required field or malformed JSON	Check the request body against the schema
invalid_scope	Token scope insufficient for the requested operation	Re-mint a token with the required scope, or contact your account manager to add the scope to your client
level3_tax_mismatch	tax_amount_cents does not reconcile with line-item totals	Recalculate tax; ±1 cent tolerance is allowed
level3_validation_failed	A Level 3 field failed validation (description >40 chars, quantity ≤0, etc.)	See the message field for the specific violation
amount_exceeds_order_total	Payment amount exceeds the remaining unpaid balance	Reduce amount_cents

HTTP 401 — Unauthorized

error	Cause	Remediation
missing_token	No Authorization header	Add Authorization: Bearer <token>
invalid_token	Token signature invalid, malformed JWT, or wrong issuer	Verify you are using a token from the M2M pool (not the POS user pool)
token_expired	JWT exp claim has passed	Re-mint a token
client_revoked	The M2M client has been revoked in the admin portal	Contact your partner_admin to issue a new client

HTTP 403 — Forbidden

error	Cause	Remediation
insufficient_scope	Token lacks the scope required for this endpoint	Re-mint with the correct scope
location_out_of_scope	The location_id does not belong to your partner subtree	Use a location returned by GET /pos/v1/locations
permission_denied	Caller does not have the required permission	Verify your client’s scopes in the admin portal

HTTP 404 — Not Found

error	Cause	Remediation
order_not_found	Order ID does not exist or is outside your partner scope	Verify the order_id
payment_not_found	Payment ID does not match the order	Verify both order_id and payment_id
location_not_found	Location ID does not exist or is outside your partner scope	Use a location from GET /pos/v1/locations
spec_not_available	Well-known spec endpoint hit but spec file not bundled	Internal — contact support

HTTP 409 — Conflict

error	Cause	Remediation
order_already_paid	Order has already been fully paid	No action needed — the order is complete
order_not_open	Attempting to pay a cancelled, voided, or expired order	Create a new order
payment_already_settled	Attempting to void a settled payment	Issue a refund instead
refund_window_expired	Processor rejects refunds older than their window	Contact the processor directly; this is a processor constraint
idempotency_conflict	Same Idempotency-Key used with different request body	Use the original request body, or use a new key

HTTP 422 — Unprocessable Entity

error	Cause	Remediation
validation_error	Request body is valid JSON but fails business-rule validation	See message for details

HTTP 429 — Too Many Requests

error	Cause	Remediation
rate_limit_exceeded	Per-client rate limit exceeded	Respect Retry-After header; consider upgrading your tier in the admin portal

HTTP 500 — Internal Server Error

error	Cause	Remediation
internal_error	Unexpected server error	Retry with exponential backoff; escalate with request_id if persistent

HTTP 503 — Service Unavailable

Returned during maintenance windows or upstream processor outages. Retry with backoff. Check status.apps.myfinterra.com for incident updates.