HTTP error codes
| Error code | Meaning | Recommended handling |
|---|---|---|
400 | Invalid request payload or parameters | Validate payload shape, required fields, and enum values before retrying. |
401 | Authentication failed | Refresh access token, retry once, then surface actionable auth guidance. |
403 | Authenticated but unauthorized | Check role/permissions in Phrase TMS and account scope. |
404 | Referenced resource not found | Verify IDs (projectUid, jobUid, template IDs) and endpoint path version. |
429 | Rate limit reached | Back off with jitter; reduce poll frequency and burst size. |
500 | Internal service error | Retry with bounded backoff; capture request context for support escalation. |
503 | Temporary service unavailability | Retry with bounded backoff; defer non-critical jobs when possible. |
Rate and async limits
Critical constraints to design for:- Phrase TMS documents an API limit of 6,000 requests per minute for logged-in users.
- API request limits require bounded polling and backoff.
- Async workflows can queue under load; avoid aggressive status polling.
- Webhooks reduce polling load and should be your primary production signal.
Use exponential backoff with jitter for retries on
429 and 5xx responses. Always treat support-doc limits as the source of truth for current values.File handling limits
Plan for file import constraints early:- Validate file type and size before upload.
- Split very large submissions into smaller batches.
- Fail fast with actionable feedback when files are unsupported.
Reliability checklist
- Implement retry classification: retry only transient errors.
- Make create/export operations idempotent.
- Track correlation IDs across inbound and outbound calls.
- Alert on repeated failure classes and webhook processing lag.
- Add fallback polling if webhook events are missed.
Next steps
Full Integration Workflow
Apply these safeguards to the full production lifecycle.
Quick Start
Build a baseline flow, then harden using this guide.