Errors

Errors return a non-2xx status code and a JSON body with a machine-readable error code, a human-readable message, and the numeric status:

{
  "error": "INSUFFICIENT_SCOPE",
  "message": "Partner does not have the required scope: tours.read",
  "status": 403
}

Authentication failures raised before your request reaches the application (at the gateway authorizer) return a bare body without an error field — { "message": "Unauthorized" } for 401 (no API key) or { "message": "Forbidden" } for 403 (a present-but-invalid key, or a bad/missing bearer token alongside a key). Always branch on the HTTP status code, not only on the body shape.

Status codes

Status	Code	When
`400`	`INVALID_JSON`	Request body is not valid JSON
`400`	`VALIDATION_ERROR`	A field failed validation (e.g. empty tour name, bad date range, invalid time zone)
`400`	`BAD_REQUEST` / `GRAPHQL_ERROR`	The underlying service rejected the input (missing required field, invalid value)
`400`	`"400"`	Tour creation rejected because the organization has reached its free-tour limit (message: “Organization has reached the free tour limit”). Note the non-semantic `error` code of `"400"`.
`401`	—	Missing API key/secret, or missing/invalid/expired bearer token. Returned as a bare `{ "message": "Unauthorized" }`.
`402`	`SUBSCRIPTION_REQUIRED`	Write operation on an organization without an active subscription
`403`	`Forbidden`	An API key is present but the request fails the gateway authorizer — the key is unknown/invalid/revoked, or the bearer token is missing/invalid alongside a key. Returned as a bare `{ "message": "Forbidden" }`.
`403`	`INSUFFICIENT_SCOPE`	Your partner credential lacks the endpoint’s required scope
`403`	`Unauthorized`	The authenticated user is not allowed to access this resource
`404`	`NOT_FOUND`	No endpoint matches the method + path, or a chat endpoint was called with a direct-message conversation
`404`	`TOUR_NOT_FOUND`	The referenced tour has been deleted
`405`	`METHOD_NOT_ALLOWED`	Path exists but not for this HTTP method (see the `Allow` response header)
`409`	`GRAPHQL_ERROR`	The request conflicts with existing data
`413`	`PAYLOAD_TOO_LARGE`	Request body exceeds 512 KB
`500`	`INTERNAL_ERROR`	Unexpected server error
`502`	`EMPTY_RESPONSE`	The underlying service returned no data

Response body examples

Concrete examples of each error response body:

// 400 — Validation error
{
  "error": "VALIDATION_ERROR",
  "message": "Tour name must not be empty",
  "status": 400
}

// 401 — Unauthorized (raised before reaching the application; no `error` field)
{
  "message": "Unauthorized"
}

// 402 — Subscription required
{
  "error": "SUBSCRIPTION_REQUIRED",
  "message": "This organization does not have an active subscription.",
  "status": 402
}

// 403 — Insufficient scope
{
  "error": "INSUFFICIENT_SCOPE",
  "message": "Partner does not have the required scope: tours.write",
  "status": 403
}

// 404 — Tour not found (soft-deleted)
{
  "error": "TOUR_NOT_FOUND",
  "message": "Tour has been deleted",
  "status": 404
}

// 405 — Method not allowed
{
  "error": "METHOD_NOT_ALLOWED",
  "message": "PATCH is not supported for /v1/tours. Allowed: GET, POST, PUT, DELETE",
  "status": 405
}

// 413 — Payload too large
{
  "error": "PAYLOAD_TOO_LARGE",
  "message": "Request body exceeds 512KB limit",
  "status": 413
}

Business rules that can block a request

Beyond authentication and scopes, several rules are enforced before a write reaches Daysync’s services:

Subscription requirement (`402`)

Write operations against an organization that has no active subscription are rejected with 402 SUBSCRIPTION_REQUIRED. Organizations flagged as unlimited-free, trial, or beta are exempt. This applies to writes where the organization is identified by the request — in practice, tour creation (POST /v1/tours).

Deleted tours (`404`)

Any request that references a tour which has been soft-deleted returns 404 TOUR_NOT_FOUND — for both reads of its children and writes against it.

Endpoints requiring several scopes (`403`)

GET /v1/tours/{tourId}/data returns data from six resources, so it requires the read scope for all of them. A partial grant is rejected with 403 INSUFFICIENT_SCOPE, and the message names exactly which scopes are missing:

{
  "error": "INSUFFICIENT_SCOPE",
  "message": "This endpoint returns data from several resources and requires all of: tours.read, schedule.read, venues.read, accommodation.read, guestlist.read, bulletins.read. Missing: bulletins.read",
  "status": 403
}

Every other endpoint requires exactly one scope. See Scopes & Permissions.

Direct messages are not exposed (`404`)

The chat endpoints cover channels and group chats only. Calling one with a 1:1 direct message conversation or a message inside one returns 404 NOT_FOUND:

{
  "error": "NOT_FOUND",
  "message": "Direct messages are not available through the public API. Only channels and group chats are exposed.",
  "status": 404
}

This is 404 rather than 403 deliberately — the response does not confirm whether the conversation exists. DMs are also filtered out of every chat list and search, so a valid integration should never encounter this. See Chat.

Input validation (`400`)

Tour create/edit requests are validated up front:

name must not be empty and must be ≤ 500 characters,
end_date must not be before start_date,
timeZone must be a valid IANA time zone (e.g. Australia/Sydney).

Other endpoints are validated by the underlying service, which surfaces a 400 with a descriptive message.

Known issue: some schedule-item validation failures are currently returned with HTTP 500 and error: "VALIDATION_ERROR" rather than 400. For example, sending startTime as an ISO 8601 datetime instead of HH:mm returns 500 with “Start Time must be in HH:mm format (24-hour format)”. Treat a 500 whose body carries error: "VALIDATION_ERROR" as an input error (fix the request) rather than a transient server fault to retry.

Error messages are sanitized

Internal errors (database constraints, SQL details, internal paths) are never returned verbatim. Such cases are collapsed to a generic message and typically a 409. Build error handling around the status and error code rather than parsing message text.

Handling tips

Treat 401 as “fix your credentials/token” and 403 as “you are authenticated but not permitted” — they require different responses (re-auth vs. request more scopes).
On 402, surface a subscription/billing prompt to the user; retrying will not help.
On 5xx, retry with backoff; these are transient or upstream.

Get started

Endpoints

Guides

Reference

Status codes

Response body examples

Business rules that can block a request

Subscription requirement (`402`)

Deleted tours (`404`)

Endpoints requiring several scopes (`403`)

Direct messages are not exposed (`404`)

Input validation (`400`)

Error messages are sanitized

Handling tips

​Status codes

​Response body examples

​Business rules that can block a request

​Subscription requirement (402)

​Deleted tours (404)

​Endpoints requiring several scopes (403)

​Direct messages are not exposed (404)

​Input validation (400)

​Error messages are sanitized

​Handling tips

Status codes

Response body examples

Business rules that can block a request

Subscription requirement (`402`)

Deleted tours (`404`)

Endpoints requiring several scopes (`403`)

Direct messages are not exposed (`404`)

Input validation (`400`)

Error messages are sanitized

Handling tips