Building

Errors, idempotency, and rate limits

Error shape

Every error returns a consistent envelope with an HTTP status, a machine-readable code, the request id, and a docs link. Every response (success or error) also carries request_id, environment, and livemode.

Error envelope

401

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "API key is invalid or revoked.",
    "param": null,
    "request_id": "req_live_...",
    "docs_url": "https://developers.mavunta.com/docs/errors#invalid_api_key"
  }
}

Common codes

Code	Meaning
`invalid_api_key`	Missing, malformed, or revoked key.
`scope_missing`	The key lacks a required scope.
`ip_not_allowed`	Request IP is not on the key allowlist.
`merchant_not_verified`	Live keys need completed KYB + live enablement.
`environment_mismatch`	The key's environment does not match the API host it was sent to.
`invalid_request`	A field is missing or invalid (see `param`).
`unsupported_asset`	The settlement asset or currency pair is not supported.
`rate_limit_exceeded`	Too many requests; slow down and retry.
`idempotency_conflict`	The `Idempotency-Key` was already used with different parameters or in the other environment.

Idempotency

Send an Idempotency-Key header on money-moving POSTs (payment intents, payment links, refunds). Replaying the same key with the same parameters returns the original result instead of creating a duplicate, so a retry after a network failure is always safe. Reusing a key with a different amount, currency, or environment returns 409 idempotency_conflict. Our SDKs add a key automatically.

Header

Idempotency-Key: order-1001

Rate limits

Requests are metered per key. Every response includes the current budget; exceeding it returns 429 rate_limit_exceeded.

Response headers

Mavunta-RateLimit-Limit: 600
Mavunta-RateLimit-Remaining: 598
Mavunta-RateLimit-Reset: 1718712000

Next: SDKs →