Errors

Every error in this API — with one exception, noted below — is an RFC 7807 problem document, served as application/problem+json:

{
    "type": "https://developer.maatstays.wtf/errors/conflict",
    "title": "Conflict",
    "status": 409,
    "detail": "These nights are already booked or held on Maat, so the block was not applied: 2026-09-02, 2026-09-03.",
    "instance": "urn:maat:request:3b1f7a90-0d4c-4d4e-9b2a-6c1f0a2e5d33",
    "code": "conflict",
    "conflicts": ["2026-09-02", "2026-09-03"]
}

Branch on code, never on type or the wording of detail. code is the contract; title and detail are for people and we reserve the right to rewrite them. instance identifies this one occurrence — it is an identifier, not a URL — and quoting it is the fastest way for your Maat contact to find the request in our logs.

The codes

`code`	Status	What happened	What to do
`validation_failed`	400	The payload does not match the published schema.	Read `errors[]` — it names each rejected field and the rule it broke. Fix the payload; do not retry unchanged.
`unauthorized`	401	No usable token: missing, malformed, expired, or its key was revoked.	Mint a fresh token and retry once. If it persists, your key has been revoked — talk to your Maat contact.
`workspace_scope_mismatch`	403	The token’s environment does not match the workspace it addresses.	You are using a sandbox token where a production one is needed, or the reverse. Check which key you exchanged. Never retry unchanged.
`property_not_found`	404	No such property in the workspace your key addresses.	Check the `listing_id` or `provider_id` you sent. Nothing was written.
`conflict`	409	The nights collide with a Maat booking or a live hold.	Act on `conflicts[]` — the complete list of colliding dates. Re-push a range that excludes them, or leave the block off. Nothing was written.
`rate_limited`	429	Too many requests for this key.	Wait `Retry-After` seconds, then resume. See Rate limits.
`internal_error`	500	Our fault.	Retry an idempotent request with backoff. If it persists, quote `instance` to your Maat contact. Use `GET /v1/blocks` to check whether a push landed.
`not_enabled`	501	The contract is published and not yet enabled for this workspace.	Nothing was written and nothing will be delivered. Expected in production before launch — your request was authenticated and validated in full, so a `501` means your integration is correct.
`service_unavailable`	503	A capability we need is not configured on our side.	Not a rejection of your request; nothing was written. Retry with backoff.

Two codes carry a typed extension member: validation_failed adds errors[] ({ field, code } per rejected field — never the value you sent), and conflict adds conflicts[] (every colliding date, untruncated). Parse those, not the prose.

One refusal, several causes — on purpose

Some errors deliberately do not say which of several checks failed. An unknown key, a revoked key and a wrong secret all answer the same 401; a sandbox/production mismatch and a workspace that does not resolve answer the same 403; a listing that does not exist and one that belongs to somebody else answer the same 404. Distinguishing them would let anyone enumerate credentials, tenants or another customer’s inventory. If you are stuck on one of these, the answer is a conversation with your Maat contact, not more requests.

The one exception

The token exchange (POST /v1/token) answers its refusals with a plain { "message": … } body rather than a problem document — you meet it once, at the start of a session. An unexpected fault there is a problem document like everywhere else.

The type URIs are stable identifiers, and code is what you should branch on. Do not fetch a type URI at runtime or assume it serves content.

Get started

Guides

Resources

API Reference

The codes

One refusal, several causes — on purpose

The one exception

​The codes

​One refusal, several causes — on purpose

​The one exception

The codes

One refusal, several causes — on purpose

The one exception