Core concepts

Errors

Error response format and the HTTP status codes the API returns.

TickOS uses conventional HTTP response codes: 2xx for success, 4xx for client errors and 5xx for server errors. Error responses are JSON objects with an error field containing a human-readable message:

response.json

JSON

01{
02  "error": "subject is required"
03}

UTF-8 · LF · JSONtickos.dev

Authentication, permission and rate limit errors also include a message field with more detail. A few endpoints add extra context fields (for example, POST /v1/emails returns domain and help when the sender domain is not configured or verified). Always read error first and treat any other field as optional.

401 response

JSON

01{
02  "error": "Invalid API key",
03  "message": "The provided API key is invalid or has been revoked"
04}

UTF-8 · LF · JSONtickos.dev

HTTP status codes

Code	When
400	Missing or malformed parameters, or an operation that is not valid for the current state (e.g. deleting an active automation).
401	Missing or invalid API key.
403	The API key does not have the required permission, the feature is not included in your plan, or the action is not allowed (e.g. the customer is blocked from creating tickets, the account is suspended).
404	The requested resource does not exist in your workspace.
409	Conflict with existing data: duplicates (tag name in the same inbox, contact group name, domain, inbox email address, pending invitation, existing member) or state conflicts (deleting a non-draft campaign, deleting a connection with active inboxes).
413	Payload too large: the email built by POST /v1/tickets/compose exceeds the maximum sendable size.
422	A recipient is suppressed (too many bounces or marked undeliverable), so the email is not sent.
429	Rate limit exceeded, or a plan quota was reached. See below.
500	Internal server error. Safe to retry idempotent requests.

429: rate limit vs. plan quota

HTTP 429 is used for two different situations. Check the error field to tell them apart.

error	Meaning	What to do
Rate limit exceeded	Too many requests per minute for this key (see Rate limits).	Wait Retry-After seconds and retry.
Limit exceeded	A plan quota was reached (e.g. monthly, daily or hourly emails, recipients per email, storage).	Do not retry immediately: wait for the quota period to reset (hourly, daily or monthly) or upgrade the plan.

Plan quota reached

JSON

01{
02  "error": "Limit exceeded",
03  "message": "Email limit reached (3000/3000). Upgrade or wait for period reset.",
04  "current": 3000,
05  "limit": 3000,
06  "percentage": 100,
07  "recommended_plan": "starter"
08}

UTF-8 · LF · JSONtickos.dev

Team member limits (POST /v1/members and POST /v1/invitations) also return 429, but with only the error field.

PreviousPagination Next Rate limits