Errors & Retries
Turnqey APIs use standard HTTP status codes with JSON responses.
Clients should separate permanent request errors from temporary failures.
Common status codes
| Status | Meaning | Retry? | Client action |
|---|---|---|---|
| 200 | Success | No | Use the response. |
| 400 | Bad request or missing parameter | No | Fix the request before trying again. |
| 401 | Token missing, expired, or invalid | Once | Request a new token and retry once. |
| 403 | Partner, IP, or permission not allowed | No | Contact Turnqey support. |
| 404 | Resource not found | No | Check the ID, collection, source, or endpoint. |
| 422 | Request understood but cannot be processed | No | Show a support path with the request details. |
| 429 | Rate limited | Yes | Back off and retry after the limit window. |
| 500 / 502 / 503 / 504 | Server or upstream failure | Yes | Retry with backoff and jitter, then fail gracefully. |
Retry guidance
Use retries only for temporary failures.
Recommended pattern:
- Retry 429 and 5xx responses with exponential backoff and jitter.
- Retry 401 once after requesting a new token.
- Do not retry 400, 403, 404, or 422 without changing the request.
- Cap retries. Three attempts is usually enough.
- Log request context for support.
What to log
Log enough context to investigate without exposing secrets.
Include:
- Endpoint
- HTTP method
- Timestamp
- Account ID, collection ID, or identity when available
- Request ID or correlation ID when available
- Status code
- Error message
Do not log:
- Client secrets
- Bearer tokens
- API keys
- OAuth authorization codes
- Seed phrases or private keys
Reconnect-required cases
Some errors mean the user must reconnect the source account.
Examples:
- OAuth refresh token revoked
- Source authorization expired
- User removed Turnqey access at the source platform
- Platform requires renewed consent
In these cases, show a clear reconnect action instead of retrying in the background.
Support
For integration support, contact: