Rate limits and error handling

Every REST response includes three rate-limit headers so your client can pace itself without guessing:

• X-RateLimit-Limit: your total request budget for the window
• X-RateLimit-Remaining: how many requests you have left
• X-RateLimit-Reset: when the window resets, as a Unix timestamp

When you exceed the limit you get a 429 with retryable set to true and the suggestion to wait 60 seconds before retrying. Honor it: back off and retry after the wait or after the Reset timestamp.

Error shape

All errors use the same structure:

• error: what went wrong, in plain language
• retryable: whether retrying can succeed. True for transient issues, false for auth or validation failures.
• suggestion: the concrete next step

Common errors

Authentication failures return 401 or 403 and the suggestion always names the fix:

• Missing or invalid API key: create or regenerate one at the dashboard API Keys page
• LinkedIn account disconnected or subscription lapsed: reconnect from the dashboard, or reactivate billing first
• Daily API limit reached: not retryable that day, the suggestion points to the billing page for higher limits
• Transient server-side errors are marked retryable true: wait a few seconds and retry, and contact support if it persists

Because retryable is machine-readable, a robust client needs only one rule: if retryable is true, back off and retry with a delay. If it is false, fix the cause named in the suggestion instead of hammering the endpoint.