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: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)
- Missing
X-Api-Keyheader - Invalid or expired API key
- Typo in the API key
Validation errors (400)
- Missing required parameters
- Invalid parameter types or values
- Malformed request body
Not found errors (404)
- Resource was deleted
- Incorrect resource ID
- Resource belongs to a different account
Request timeout errors (408)
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)
Retry-After: Seconds to wait before retrying
Billing errors (402)
- 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
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)
Complete error handling example
Request tracing
Every response includes anX-Request-Id header:
Best practices
Always check response status codes
Always check response status codes
Don’t assume requests succeed. Check status codes and handle errors appropriately.
Implement exponential backoff
Implement exponential backoff
For retryable errors (429, 5xx), use exponential backoff to avoid overwhelming the API.
Log request IDs
Log request IDs
Store
X-Request-Id values in your logs for debugging and support requests.Use idempotency keys for retries
Use idempotency keys for retries
When retrying mutating operations, use the same idempotency key to avoid duplicates.
Don't retry client errors
Don't retry client errors
4xx errors (except 429) indicate issues with your request. Fix the request rather than retrying.
Getting help
When contacting support about errors:- Include the
X-Request-Idheader value from the response - Describe what you were trying to do
- Include the request method and endpoint
- Note the approximate time of the error
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