Errors

All errors return a JSON body with an error string. HTTP status codes follow standard conventions.

Error format

{
  "error": "Session required"
}

Some errors include additional context:

{
  "error": "Validation failed",
  "details": "responses must be an array of {item_id, value} objects"
}

Common error codes

Status	Error string	Meaning
400	Validation failed	Malformed request body or missing required fields
401	Session required	Endpoint requires a valid mn_session cookie
401	Invalid token	API key missing, malformed, or revoked
403	Purchase required	User has not purchased the Situation Map
403	Forbidden	Valid session but insufficient role
404	Not found	Resource does not exist
429	Rate limit exceeded	Too many requests — back off and retry
500	Internal error	Server-side failure — contact support if persistent

Auth errors in detail

401 Session required — The request reached a session-gated endpoint without a valid mn_session cookie. Start the auth flow via POST /auth/request.

403 Purchase required — The user’s session is valid but they have not purchased the MN Situation Map. Direct them to the checkout flow before calling /map/intake.

Retries

Retry 429 and 5xx responses with exponential backoff. Do not retry 4xx responses — they indicate a problem with the request itself.