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 is valid but lacks the required scope for this endpoint
`404 Not Found`	The requested resource does not exist on your account
`422 Unprocessable Entity`	One or more query 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.

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. When you exceed this 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 ID or service slug 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 or slug belongs to a resource on your account before assuming it doesn’t exist.

Overview

Endpoints

API errors and HTTP status codes

Error codes

Standard error body

Validation error body (422)

Rate limiting (429)

404 and user isolation

​Error codes

​Standard error body

​Validation error body (422)

​Rate limiting (429)

​404 and user isolation

Error codes

Standard error body

Validation error body (422)

Rate limiting (429)

404 and user isolation