Error Handling & Troubleshooting

HTTP Status Codes

Status Code	Meaning	Common Causes
`400`	`Bad Request`	Invalid/missing parameter, malformed JSON, etc.
`401`	`Unauthorized`	Missing or invalid API key.
`402`	`Insufficient Credits`	You lack the credits to proceed with the request.
`404`	`Not Found`	Requested job or resource doesn't exist; invalid URL for metadata.
`429`	`Too Many Requests`	Rate limiting or concurrency limit reached. Check response headers for retry information.
`500`	`Internal Server Error`	Unexpected server issue. Check status.importly.io if needed.

Rate Limiting (429 Errors)

When you exceed rate limits, you'll receive detailed error responses:

Rate Limit Exceeded Response

json
1{
2  "success": false,
3  "error": "Rate limit exceeded. Limit: 240 requests per 1 h",
4  "limit": 240,
5  "remaining": 0,
6  "reset": 1709901234000,
7  "retryAfter": 3600,
8  "endpoint": "/import"
9}

Concurrency Limit Exceeded Response

json
1{
2  "success": false,
3  "error": "Concurrent limit exceeded. Max 2 concurrent import jobs allowed.",
4  "concurrentLimit": 2,
5  "currentConcurrent": 2,
6  "endpoint": "/import"
7}

Rate Limit Headers

All API responses include these headers for monitoring:

X-RateLimit-Limit: Total requests allowed per window
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when limit resets
X-RateLimit-Window: Time window (e.g., "1 h")
X-RateLimit-Plan: Your current plan (free/paid)

Handling Rate Limits

Monitor Headers: Check rate limit headers before hitting limits
Implement Backoff: Use exponential backoff based on retryAfter
Respect Concurrency: Wait for jobs to complete before starting new ones
Cache Results: Store metadata responses to avoid repeated calls

Common Troubleshooting Tips

Check URL Accessibility: If /metadata or /import returns a 404, confirm the media URL is publicly available.
API Key Validity: Rotate your key if you suspect it's expired or compromised.
Insufficient Credits: Monitor usage in the dashboard and top up or upgrade your plan if needed.
Rate Limit Issues: Check response headers and implement proper backoff strategies.

Contact Support

If you're stuck, reach out to [email protected] with:

The jobId or request payload.
Timestamps or logs for the failing requests.
Any relevant code snippets.

S3 Storage Integration Billing & Usage