Skip to main content

Error Handling

Ticksupply uses consistent error responses across all endpoints. This guide covers error formats, common error codes, and best practices for handling errors.

Error response format

All errors follow this structure:
When the server has structured context to share, the optional details field is included with free-form JSON:
Every response also includes an X-Request-Id header (e.g., req_7f8e9d0c1b2a3456). Include this value when contacting support.
Match on code rather than message. Message text is for humans and may change; code is the stable contract.

Error codes reference

Handling errors by type

Authentication errors (401)

Common causes:
  • Missing X-Api-Key header
  • Invalid or expired API key
  • Typo in the API key
Solution:

Validation errors (400)

Common causes:
  • Missing required parameters
  • Invalid parameter types or values
  • Malformed request body
Solution:

Not found errors (404)

Common causes:
  • Resource was deleted
  • Incorrect resource ID
  • Resource belongs to a different account
Solution:

Request timeout errors (408)

Every endpoint has a hard 10-second deadline. If your request doesn’t finish within that window, you receive a 408 with the standard error envelope. This is rare under normal conditions — typical responses are tens of milliseconds — and usually indicates transient backend pressure. Solution: Retry with exponential backoff. If the same endpoint times out repeatedly, contact support with the X-Request-Id.
Heavy operations like creating an export return 202 Accepted immediately and finish asynchronously, so they never hit the 10-second deadline. Poll the resulting job for completion instead.

Rate limit errors (429)

Headers included:
  • Retry-After: Seconds to wait before retrying
Solution:

Billing errors (402)

Common causes:
  • Trial account has reached its stream or export size limit
  • Account is suspended for non-payment
  • Account is in a billing grace period with restricted actions
  • Plan does not include the requested action
Returned by: POST /v1/subscriptions, POST /v1/subscriptions/{id}/resume, and POST /v1/exports. Solution: Retrying does not help — the underlying billing state must change. Upgrade your plan, update your payment method, or wait for your trial to convert in billing settings.

Server errors (500, 503)

Solution:

Complete error handling example

Request tracing

Every response includes an X-Request-Id header:
Log the X-Request-Id for all requests. When contacting support, include this ID to help us investigate issues quickly.

Best practices

Don’t assume requests succeed. Check status codes and handle errors appropriately.
For retryable errors (429, 5xx), use exponential backoff to avoid overwhelming the API.
Store X-Request-Id values in your logs for debugging and support requests.
When retrying mutating operations, use the same idempotency key to avoid duplicates.
4xx errors (except 429) indicate issues with your request. Fix the request rather than retrying.

Getting help

When contacting support about errors:
  1. Include the X-Request-Id header value from the response
  2. Describe what you were trying to do
  3. Include the request method and endpoint
  4. Note the approximate time of the error
Email: support@ticksupply.com

Next steps

Rate Limiting

Understand rate limits and how to handle them

Idempotency

Safely retry requests using idempotency keys

Pagination

Navigate large result sets efficiently

API Reference

Explore the complete API documentation
Last modified on May 9, 2026