Errors

The Tourical API uses standard HTTP status codes. Every non-2xx response carries a Content-Type: application/problem+json body following RFC 7807.

Problem document shape

{
  "type": "https://developers.tourical.com/errors/scope-required",
  "title": "Missing required scope",
  "status": 403,
  "detail": "This endpoint requires the `trips:write` scope.",
  "required_scope": "trips:write"
}

type, title and status are always present; detail almost always is. Some problems add members of their own — required_scope above, errors on a validation failure, next on the booking hand-off.

Branch on type, not on title or detail. type is the stable machine identifier: an absolute URL ending in the problem's slug, which never changes once shipped. title and detail are human-facing prose and may be reworded.

Field-level validation errors add an errors map keyed by field path:

{
  "type": "https://developers.tourical.com/errors/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields failed validation.",
  "errors": {
    "url": ["URL must use https:"],
    "events": ["Unknown event type. Allowed: booking.confirmed, ..."]
  }
}

Status codes

There is no 400 and no 402 on /v1/*: a malformed body is a 422, a missing credential is a 401, and the plan gate is a 403.

Tracing a request

Every response carries a Tourical-Request-Id header. Send it back to us in any bug report and we can correlate to the exact request in our logs.

You can also send your own request id by setting the Tourical-Request-Id header on the request — we'll echo it back instead of generating one. Useful when you already trace requests in your own system.

curl https://app.tourical.com/api/v1/trips \
  -H "Authorization: Bearer tk_live_..." \
  -H "Tourical-Request-Id: $(uuidgen)"

Retry guidance

For write endpoints (POST, PATCH, DELETE), a 5xx response means the server may or may not have completed the action. Send an Idempotency-Key on the first attempt and reuse it on every retry: 5xx responses are never stored against the key, so the retry re-executes, while a write that did land is replayed instead of repeated.

Problem type catalog

Every type below is prefixed with https://developers.tourical.com/errors/.