Rate Limits & Errors

Rate Limits

The TechLadder API enforces rate limits to ensure fair usage and platform stability.

Limit	Default	Description
Requests per minute	300	Total API calls per minute per API key
Max batch size	10,000	Maximum contacts per batch
Max concurrent calls	20	Simultaneous active calls per account
Max call duration	900s (15 min)	Maximum duration per individual call

tip

If you need higher limits, contact us at info@techladder.ai to discuss your requirements.

Rate Limit Headers

Every response includes rate limit information in the headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1715698800

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 response:

{
  "status_code": 429,
  "message": "Rate limit exceeded. Please retry after 30 seconds.",
  "error": {
    "code": "RATE_LIMITED",
    "details": ["Maximum 300 requests per minute"]
  },
  "data": null
}

Best practice: Implement exponential backoff with jitter:

import time
import random

def make_request_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        response = func()
        if response.status_code != 429:
            return response
        wait = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(wait)
    raise Exception("Max retries exceeded")

HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
202	Accepted	Request accepted for processing (async)
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
422	Validation Error	Request body failed validation
429	Rate Limited	Too many requests
500	Server Error	Internal server error — contact support

Common Error Codes

Error Code	HTTP Status	Description
UNAUTHORIZED	401	API key is missing or invalid
FORBIDDEN	403	API access not enabled for account
NOT_FOUND	404	The requested resource was not found
VALIDATION_ERROR	422	Request body contains invalid data
BATCH_SIZE_EXCEEDED	400	Batch exceeds maximum contact limit
DUPLICATE_PHONE	400	Duplicate phone number in batch
INVALID_PHONE	422	Phone number format is invalid
RATE_LIMITED	429	Rate limit exceeded
BATCH_ALREADY_STARTED	409	Batch has already been started
BATCH_NOT_STARTABLE	422	Batch is not in a startable state