Errors and rate limits

Error format (RFC 7807)

Every error response is a problem document with content type
application/problem+json, following RFC 7807.
The shape is consistent, so you can handle errors generically:

{
  "type": "https://docs.montavire.com/reference/errors#validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request constraints were violated.",
  "errors": [
    { "field": "contact_email", "message": "must be a valid email address" }
  ]
}

type, title, status, and detail are always present.
The type URL deep-links to this errors page. Known type slugs are
validation, bad-request, conflict, not-found, and forbidden.
On validation failures, an errors array lists the offending fields so you can
surface field-level messages to users.

Status codes you will see

Status	Meaning	What to do
`400 Bad Request`	Malformed request or failed validation	Read the `errors` array and fix the body
`401 Unauthorized`	Missing or invalid `X-API-Key`	Check the key and environment prefix
`403 Forbidden`	Key lacks the required scope	Grant the scope, or use a key that has it
`404 Not Found`	No such resource in your tenant	Check the id
`409 Conflict`	Idempotency-key reused with a different body, or a state conflict	Use a fresh key, or reconcile state
`429 Too Many Requests`	Rate limit exceeded	Back off using the headers below
`5xx`	Server error	Retry with backoff; the request may be safe to replay with the same `Idempotency-Key`

Rate limits

Requests are throttled per key on rolling minute, hour, and day
windows. Every response carries your current standing so you can pace yourself
before hitting a limit:

Header	Meaning
`X-RateLimit-Limit`	Canonical (per-minute) ceiling
`X-RateLimit-Limit-Minute` / `-Hour` / `-Day`	Ceiling for each window
`X-RateLimit-Remaining-Minute` / `-Hour` / `-Day`	Requests left in each window

When you exceed a limit you get 429 Too Many Requests with:

Header	Meaning
`Retry-After`	Seconds to wait before retrying (standard HTTP header)
`X-RateLimit-Retry-After-Seconds`	Same value, explicit name

Recommended client behaviour

Read X-RateLimit-Remaining-* and slow down as it approaches zero.
On 429, sleep for Retry-After seconds, then retry. Add jitter if you run
many workers.
Prefer webhooks over tight polling loops: let Montavire push state
changes to you instead of asking repeatedly.