Errors
Last verified: 2026-06-20 (Task #390 — User APIs documentation).
The Trips & Itinerary API returns resource objects on success and a simple error object on failure:
{ "error": "Access denied" }
For request-body validation failures, error is instead an array of
structured validation issues:
{ "error": [ { "path": ["base_revision"], "message": "Required" } ] }
Status codes
| Status | Meaning | Typical error |
|---|---|---|
400 | Malformed request — bad id, invalid body, or (for proposals) an already-resolved/expired proposal. | "Invalid trip id" or a validation-issues array |
401 | No valid session cookie or bearer token. | "Authentication required" |
403 | Authenticated but not authorized — not a member, insufficient role, or (permissions) not the owner. | "Access denied" |
404 | The trip, proposal, or user was not found. | "Trip not found" |
409 | Timeline operation conflict — stale base_revision or failed validation. | "Revision conflict" (with code: STALE_REVISION) |
500 | Unexpected server error. | "Internal server error" |
Handling 409 conflicts
The 409 body carries a code field:
code | What to do |
|---|---|
STALE_REVISION | Re-read the itinerary (or call the diff endpoint), re-apply your change against the new revision, and retry. |
VALIDATION_FAILED | The operation is invalid against the current timeline; read the error message and adjust the payload. |
See operations.md for a worked example.