Errors & Rate Limits

This page covers HTTP status codes, error response format, rate limiting, and common troubleshooting steps.

Error Response Format

All API errors return a consistent JSON structure:

{
  "detail": "Campaign not found",
  "error_code": "RESOURCE_NOT_FOUND",
  "status": 404
}

Validation errors include a fields array:

{
  "detail": "Validation failed",
  "error_code": "VALIDATION_ERROR",
  "status": 422,
  "fields": [
    { "field": "commission_amount", "message": "Must be a positive number" },
    { "field": "name", "message": "Required field" }
  ]
}

HTTP Status Codes

Code	Meaning	Common Cause
200	OK	Request succeeded
201	Created	Resource created successfully
204	No Content	Delete succeeded
400	Bad Request	Malformed JSON or invalid parameters
401	Unauthorized	Missing or expired token
403	Forbidden	Insufficient permissions or scopes
404	Not Found	Resource does not exist
409	Conflict	Duplicate resource or state conflict
422	Unprocessable Entity	Validation errors
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error (contact support)

Error Codes

Error Code	Description
TOKEN_EXPIRED	Access token has expired; refresh it
TOKEN_INVALID	Token is malformed or revoked
INSUFFICIENT_SCOPE	API key lacks the required scope
RESOURCE_NOT_FOUND	The requested resource does not exist
VALIDATION_ERROR	One or more fields failed validation
DUPLICATE_RESOURCE	A resource with the same unique key exists
RATE_LIMIT_EXCEEDED	Too many requests; slow down
CAMPAIGN_NOT_ACTIVE	Action requires an active campaign
AFFILIATE_NOT_APPROVED	Affiliate must be approved first
PAYMENT_REQUIRED	Feature requires a paid plan
QUOTA_EXCEEDED	Plan limit reached (e.g., max links)

Rate Limits

Rate limits are applied per API key or per user token:

Plan	Requests per Minute	Requests per Day
Free	30	1,000
Starter	60	5,000
Pro	300	50,000
Business	600	200,000
Enterprise	Custom	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1711036800

When rate limited, you receive a 429 response:

{
  "detail": "Rate limit exceeded. Retry after 42 seconds.",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 42
}

Troubleshooting

Problem	Solution
401 on every request	Check that your token is in the Authorization: Bearer <token> header
401 after working previously	Your access token expired; use the refresh token
403 with a valid token	Verify your API key has the required scopes
404 for a known resource	Check the resource ID and ensure you have access
422 validation errors	Review the fields array for specific issues
429 rate limited	Implement exponential backoff; check retry_after
500 server error	Retry once after 5 seconds; contact support if persistent

Best Practices

• Implement automatic retry with exponential backoff for 429 and 5xx errors.
• Log the error_code field for programmatic error handling.
• Monitor X-RateLimit-Remaining to proactively throttle requests.
• Use the narrowest API key scopes to minimize the blast radius of a leaked key.

Next Steps

• Authentication reference
• Contact support for persistent issues