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:

{
  "error": "RESOURCE_NOT_FOUND",
  "message": "Campaign not found"
}

Errors may include additional context in the detail field:

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

Optional fields may also be present:

• path — Request path that triggered the error
• request_id — Unique correlation ID for tracing through logs
• retry_after — Seconds to wait before retrying (rate limits, timeouts)

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
AUTH_REQUIRED	Missing authentication token
AUTH_INVALID_CREDENTIALS	Invalid email or password
AUTH_TOKEN_EXPIRED	Access token has expired; refresh it
AUTH_TOKEN_INVALID	Token is malformed or revoked
AUTH_INSUFFICIENT_PERMISSIONS	API key lacks the required scope
RESOURCE_NOT_FOUND	The requested resource does not exist
RESOURCE_CONFLICT	Resource state conflict or duplicate unique key
RESOURCE_ALREADY_EXISTS	A resource with the same unique key exists
RESOURCE_LOCKED	Resource is locked and cannot be modified
VALIDATION_ERROR	One or more fields failed validation
VALIDATION_FIELD_REQUIRED	Required field is missing
VALIDATION_FIELD_INVALID	Field value is invalid
VALIDATION_INVALID_REQUEST	Request body is malformed
BUSINESS_RULE_VIOLATION	Action violates business rules
BUSINESS_QUOTA_EXCEEDED	Plan limit reached (e.g., max links, max calls)
BUSINESS_LIMIT_EXCEEDED	Feature limit reached
BUSINESS_RATE_LIMIT_EXCEEDED	Too many requests; slow down
EXTERNAL_SERVICE_ERROR	Third-party service error (Stripe, PayPal, etc.)
EXTERNAL_TIMEOUT	Third-party service timeout
EXTERNAL_UNAVAILABLE	Third-party service unavailable
INTERNAL_ERROR	Unexpected server error
INTERNAL_DATABASE_ERROR	Database operation failed
INTERNAL_DATABASE_CONNECTION_ERROR	Cannot connect to database
INTERNAL_DATABASE_INTEGRITY_ERROR	Data integrity constraint violation
OPERATION_FAILED	Operation failed for unknown reason
OPERATION_TIMEOUT	Operation exceeded time limit
OPERATION_CANCELLED	Operation was cancelled

Rate Limits

Rate limits are applied per endpoint category, with higher limits for authenticated users and premium tier users. Limits are enforced using a sliding window algorithm.

Rate Limit Categories

Category	Endpoints	Limit per Minute
Auth status	/auth/status, /auth/csrf-token	3,600
Auth operations	/auth/, /login, /register, /token	1,200
Payments	/payment, /stripe, /paypal, /billing	60
Email	/email, /send-summary	20
Analytics	/analytics, /dashboard, /reports, /stats	500
AI endpoints	/ai/, /content-wizard	30
Affiliate	/affiliates, /commissions, /earnings	120
Admin	/admin, /manage, /control	300
Health checks	/health, /status, /ping	1,000
Default	All other endpoints	200

User Tier Multipliers:

• Anonymous: 1.0x
• Authenticated: 2.0x
• Premium tier: 5.0x
• Admin: 10.0x

For example, an authenticated user on the default category gets 200 × 2.0 = 400 requests per minute.

When rate limited, you receive a 429 response:

{
  "error": "BUSINESS_RATE_LIMIT_EXCEEDED",
  "message": "Too many requests to analytics endpoints. Limit: 500 per minute.",
  "retry_after": 60
}

Authentication Rate Limits

Additional strict rate limits apply to security-sensitive auth endpoints per IP address:

Endpoint	Limit	Window
Login	5 attempts	15 minutes
2FA verification	5 attempts	5 minutes
Email verification	3 attempts	15 minutes
Password reset request	3 attempts	15 minutes
Password reset confirm	10 attempts	15 minutes
Token refresh	60 attempts	15 minutes
Export operations	10 attempts	15 minutes

When an auth endpoint is rate limited, the response includes a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later.",
  "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 endpoint at /api/auth/refresh
403 with a valid token	Verify your API key/token has the required permissions
404 for a known resource	Check the resource ID and ensure you have access to it
422 validation errors	Review the detail array for specific field validation issues
429 rate limited	Check the retry_after field and wait before retrying; implement exponential backoff
500 server error	Retry once after 5 seconds; contact support if persistent

Best Practices

• Always include the retry_after header or response field when you receive a 429 response.
• Implement automatic retry with exponential backoff for rate limit (429) and server (5xx) errors.
• Log the error field for programmatic error handling and debugging.
• Use the narrowest API key scopes and permissions to minimize the blast radius of a leaked token.
• Monitor your request volume against the rate limit tiers to avoid unexpected rate limiting.
• For bulk operations (e.g., generating many links), consider using dedicated bulk endpoints like /api/batch-link-generator which have optimized rate limits.

Next Steps

• Authentication reference
• Contact support for persistent issues