Errors

Errors use RFC 9457 Problem Details, with a stable code you can switch on:

{
  "type": "https://docs.partners.loops.sa/errors/scope_not_granted",
  "title": "Scope not granted",
  "status": 403,
  "code": "scope_not_granted",
  "detail": "The merchant has not granted orders:read to this application.",
  "request_id": "req_01J9X7P2QK"
}

• Switch on code, not on title or detail; those may be reworded.
• Log request_id (also sent as the Loops-Request-Id header) and include it when you contact support.

Codes

Status	code	Meaning	What to do
400	invalid_request	A parameter is invalid; see errors[]	Fix the request
400	merchant_required	Loops-Merchant-Id missing	Add the header
401	unauthorized	Token missing, expired or invalid	Get a new token
403	insufficient_scope	Your application isn’t approved for this scope	Request the scope in the portal
403	scope_not_granted	The merchant didn’t grant this scope	Ask the merchant, or skip the feature
403	connection_not_active	The merchant revoked access	Stop calling for this merchant
403	application_suspended	Loops suspended your application	Contact partners@loops.sa
403	channel_not_permitted	The connection doesn’t include this channel	Skip this channel
404	not_found	Doesn’t exist, or isn’t shared with you	Check the ID and the connection’s locations
404	merchant_not_found	Unknown merchant ID	Check the header value
429	rate_limited	Too many requests	Wait Retry-After seconds
503	upstream_unavailable	A Loops service is temporarily unavailable	Retry with exponential backoff

Retrying safely

• Retry 429, 503 and network errors with exponential backoff and jitter.
• Don’t retry other 4xx responses without changing the request.
• GET requests are always safe to retry.