Errors and rate limits

Error shape

All 4xx/5xx responses return a JSON envelope:

{
  "message": "user payment method not found",
  "status_code": 404,
  "details": "payment method 00000000-0000-0000-0000-000000000010 not found for user 00000000-0000-0000-0000-000000000001"
}

message is always present. status_code appears on flights and offer error paths but is omitted on profile and passenger handlers — trust the HTTP status, not the body field. details carries a validation error or provider-forwarded string.

Validation failures return a ValidationError shape with a fields map; see the OpenAPI spec.

OAuth-style errors are the exception: the token endpoint (RFC 6749 §5.2) and scope-enforcement denials (RFC 6750) use the error / error_description envelope instead, so OAuth client libraries can dispatch on error directly:

{
  "error": "insufficient_scope",
  "error_description": "the token's granted scopes do not allow this request",
  "scope": "payments.read"
}

Status code semantics

Code	Meaning
400	Validation failed or malformed body.
401	Missing or invalid bearer token. Refresh and retry.
403	Token valid but access denied. Two variants: the generic envelope (user’s own permissions deny — do not retry) and {"error":"insufficient_scope", "scope":"..."} (scoped token lacks the named scope — re-authorize requesting it, then retry). The RFC 6750 challenge arrives as x-amzn-remapped-www-authenticate.
404	Resource does not exist or is soft-deleted.
409	Conflict — usually idempotency-key collision or stale offer.
429	Rate limited. Back off.
500	Server error. Retry idempotent reads after backoff.
502	Upstream provider error. Retry only if idempotent.

Retry guidance

• Idempotent reads (GET) — retry freely with exponential backoff (1s, 2s, 4s, 8s) plus jitter.
• Other writes — treat 5xx as ambiguous; read the resource back before retrying.
• 429 — does not carry Retry-After. Use the same backoff schedule.

Booking failure playbook

The booking POST is the highest-stakes call. Always send an idempotency_key. Treat outcomes as:

• 2xx — success; persist booking.id.
• 4xx with status_code — terminal; surface to user, do not retry.
• 5xx, network error, or timeout — ambiguous; replay with the same idempotency_key. Movmo deduplicates and returns the original booking.
• 409 on replay — the original request succeeded; the body is the original booking.

Rate limits

API Gateway throttles partner traffic per usage plan. Today’s commercial tier is 200 requests/second sustained, 400 burst, 5,000,000 requests/month. Exact numbers are confirmed at onboarding and may be tuned per partner.

MCP routes are throttled to 0 RPS for keyed clients. API key usage plans (Public Website, Customer, Aviare) explicitly block /v1/mcp/* so a request carrying x-api-key against MCP returns 429. This is intentional — MCP requests authenticate via Authorization: Bearer only and must not include the API key. Send the key on REST, the Bearer on MCP, never both on the same request.

WAF additionally enforces stricter IP-level caps on auth-sensitive endpoints, evaluated per source IP over a five-minute window:

Endpoint	Limit per IP / 5 min
/v1/users/me/contact/*	20
/v1/users/me/phone/verify/*	20
/v1/oauth/register	10
/v1/mcp	100

Aggregate behavior server-side. Contact us before pushing traffic that may exceed these.