SafarAPI — Morocco travel API for banks & fintechs

Every error response uses the same JSON envelope. Branch on code, not on the message — messages are English-only (for your logs) and may be reworded; code is stable and documented.

{
  "code": "validation.required.field",
  "message": "Field 'rate_pack_id' is required.",
  "request_id": "req_8f3a1c9e2b7d40",
  "details": { "field": "rate_pack_id" }
}

Field	Notes
`code`	Stable i18n code, form `domain.subdomain.detail`. Branch on this.
`message`	English, for your logs. Never localized server-side.
`request_id`	Quote this when contacting support — it correlates with Safariat logs.
`details`	Optional structured context (offending field, expected value).

HTTP status mapping

Status	Meaning
`400`	Malformed request (syntactic validation).
`401`	API key missing, invalid, expired, or incorrect HMAC signature.
`403`	Authenticated but not authorized (missing scope, non-allowlisted IP).
`404`	Resource does not exist or is inaccessible for this partner.
`409`	Same `Idempotency-Key` reused with a different body. No action performed.
`422`	Syntactically correct but a business rule was violated.
`429`	Rate limit exceeded for the current key.
`500`	Internal error — Safariat is notified automatically.
`503`	Service temporarily unavailable. Retry later.

Stable error codes

These codes are part of the contract and will not be renamed within v1.

Code	Typical status	When
`auth.api_key.missing`	401	No `Authorization` bearer sent.
`auth.api_key.invalid`	401	Unknown, expired, or revoked key.
`auth.signature.invalid`	401	`X-Signature` does not match (production writes).
`auth.timestamp.skew`	401	`X-Timestamp` outside the ±5 min window.
`validation.required.field`	400	A required field is missing — see `details.field`.
`adventure.not.found`	404	Unknown `adventure_slug`.
`adventure.capacity.exhausted`	422	No remaining capacity on the requested slot.
`booking.not.cancellable`	422	Booking already cancelled/completed or past its cancellation window.
`payment.amount.mismatch`	422	`payment_confirmation` amount differs from the quote.
`partner.credit.limit.exceeded`	403	Partner credit ceiling reached.
`idempotency.key.required`	400	`Idempotency-Key` missing on a write — see Idempotency.
`idempotency.key.too.long`	400	`Idempotency-Key` longer than 255 characters.
`idempotency.key.conflict`	409	`Idempotency-Key` reused with a different body — see Idempotency.
`rate_limit.exceeded`	429	See Rate limiting.

Unrecognized codes may be added over time (additive, never breaking). Treat an unknown code as a generic failure of its HTTP status class.