API Rate Limits & Error Codes

Connect my tools4 min readUpdated 2026-03-12

API Rate Limits & Error Codes

This guide covers the rate limits applied to JustCall API requests, the error codes you may encounter, and strategies for building a resilient integration.

Rate Limits

Rate limits are applied per API key on a rolling per-minute window.

Plan	Requests per minute	Concurrent connections
Team	60	5
Pro	120	10
Business	300	25
Enterprise	Custom	Custom

When you exceed the limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

Rate Limit Headers

Every response includes these headers so you can monitor your usage:

Header	Description
`X-RateLimit-Limit`	Your per-minute request allowance
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Error Codes

HTTP Code	Error	Description	What to do
400	Bad Request	Missing or invalid parameters in your request	Check the request body and query parameters
401	Unauthorized	Invalid or missing API key and secret	Verify your `Authorization` header format
403	Forbidden	Your plan does not include this feature, or insufficient role	Confirm plan-level access; use Admin credentials
404	Not Found	The requested resource does not exist	Check the resource ID or endpoint path
422	Unprocessable Entity	The request is well-formed but contains invalid data	Review field values (e.g., invalid phone number format)
429	Too Many Requests	Rate limit exceeded	Wait for `Retry-After` seconds, then retry
500	Internal Server Error	An unexpected error on JustCall's side	Retry after a short delay; contact support if persistent
502	Bad Gateway	Temporary upstream issue	Retry after 5-10 seconds
503	Service Unavailable	JustCall is temporarily down for maintenance	Retry after 30-60 seconds

Error Response Format

{
  "status": "error",
  "message": "Rate limit exceeded. Retry after 45 seconds.",
  "error_code": "RATE_LIMIT_EXCEEDED"
}

Retry Strategies

Exponential Backoff

For 429 and 5xx errors, use exponential backoff with jitter:

# Pseudocode
wait_time = min(base_delay * 2^attempt + random_jitter, max_delay)

Attempt	Base delay	Wait (approx.)
1	1s	1-2s
2	1s	2-4s
3	1s	4-8s
4	1s	8-16s
5	1s	16-32s

Stop retrying after 5 attempts and log the failure for manual review.

Best Practices

Respect Retry-After — When present, always wait at least the specified number of seconds before retrying.
Do not retry 400, 401, 403, or 404 — These are client errors that will not resolve on their own. Fix the request first.
Add jitter — Random jitter prevents multiple clients from retrying at the exact same moment (thundering herd).
Log every error — Record the HTTP status, response body, and timestamp so you can diagnose patterns.

Troubleshooting Common Issues

"401 Unauthorized" on every request

Confirm you are sending both the API key and secret separated by a colon in the Authorization header.
Make sure there are no extra spaces or newline characters in the header value.
Regenerate your credentials in Settings → API & Webhooks if the issue persists.

"404 Not Found" when calling a valid endpoint

Verify you are using the V2 base URL: https://api.justcall.io/v2/.
Check that the resource ID in the URL path exists in your account.

"429 Too Many Requests" during bulk operations

Reduce your request rate to stay within your plan's limit.
Batch operations where possible (e.g., use the bulk contacts endpoint instead of individual creates).
Consider upgrading your plan for higher limits.