API errors and HTTP status codes

The Tikk API uses standard HTTP status codes to signal success and failure. Every error response includes a JSON body with at least a message field describing what went wrong. Build your error handling around the HTTP status code first, then read message for additional context.

Error codes

Status	When it occurs
`401 Unauthorized`	No credential was sent or the credential is revoked, expired or unrecognized
`403 Forbidden`	The credential lacks the required scope or the request needs the Pro plan
`404 Not Found`	The requested resource does not exist on your account
`409 Conflict`	The request can’t be applied to the resource as it is now
`422 Unprocessable Entity`	One or more query or body parameters failed validation
`429 Too Many Requests`	You have sent more than 60 requests in a 60-second window

Standard error body

All errors except 422 return a JSON body with a single message field:

{
  "message": "Unauthenticated."
}

Check the message value for a human-readable description. Don’t rely on the exact wording in code. Key your error handling on the HTTP status code.

Plan required (403)

Creating a default service beyond the Free plan’s limit returns 403 with an extra error field:

{
  "message": "Upgrade to Pro to create more than 1 service.",
  "error": "plan_required",
  "required_plan": "pro",
  "upgrade_url": "https://app.tikk.chat/billing"
}

Branch on error to show an upgrade prompt. See Scopes.

Conflict (409)

DELETE /services/{id} returns 409 for a single-use service that has already been booked, and PATCH /services/{id} returns 409 for any single-use service.

Validation error body (422)

When a request fails validation, the response body includes an errors object keyed by the name of each invalid parameter. Each key maps to an array of one or more error strings describing the problem with that parameter:

{
  "message": "The to field must be a date after or equal to from.",
  "errors": {
    "to": ["The to field must be a date after or equal to from."]
  }
}

Iterate over the errors object to surface specific field-level messages to your users or logs.

Rate limiting (429)

Tikk allows 60 requests per minute per credential. Every successful response carries the current state:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per minute.
`X-RateLimit-Remaining`	Requests left in the current minute.

When you exceed the limit, the API responds with 429 Too Many Requests and includes a Retry-After header indicating the number of seconds to wait before retrying:

HTTP/1.1 429 Too Many Requests
Retry-After: 42

Read the Retry-After header and pause your requests for at least that many seconds before retrying. The following example shows how to handle a 429 response and respect the header:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = parseInt(
      response.headers.get("Retry-After") ?? "60",
      10,
    );
    console.warn(`Rate limited. Retrying in ${retryAfter}s...`);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
  }

  throw new Error("Max retries reached after repeated 429 responses.");
}

In production integrations, combine the Retry-After header with exponential backoff and jitter so that multiple instances of your service do not all retry simultaneously after a rate-limit window resets. A simple rule: always wait at least as long as Retry-After specifies, then add a random delay before the next attempt.

404 and user isolation

The API enforces strict user isolation. A booking or service ID that exists but belongs to another user returns 404 Not Found, not 403 Forbidden. The API never confirms whether a resource exists outside your account. On a 404, check the ID belongs to a resource on your account before assuming it doesn’t exist.

Overview

Profile

Services

Availability

Bookings

API errors and HTTP status codes

Error codes

Standard error body

Plan required (403)

Conflict (409)

Validation error body (422)

Rate limiting (429)

404 and user isolation

​Error codes

​Standard error body

​Plan required (403)

​Conflict (409)

​Validation error body (422)

​Rate limiting (429)

​404 and user isolation

Error codes

Standard error body

Plan required (403)

Conflict (409)

Validation error body (422)

Rate limiting (429)

404 and user isolation