> ## Documentation Index
> Fetch the complete documentation index at: https://developers.phrase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling and Limits

> Handle HTTP failures, retries, and Phrase TMS limits safely in plugin integrations.

Use this page as your operational reference for runtime failures and platform constraints.

## 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.

<Note>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.</Note>

Reference:

* [TMS limits (support)](https://support.phrase.com/hc/en-us/articles/5784117234972-Phrase-TMS-Limits)
* [Handling API rate limits](/en/api/tms/latest/handling-api-rate-limits)
* [Handling concurrent API limits](/en/api/tms/latest/handling-concurrent-api-limits)

## 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.

Reference:

* [File import settings and limits](https://support.phrase.com/hc/en-us/sections/5709618056604-File-Import-Settings)

## 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

<CardGroup cols={2}>
  <Card title="Full Integration Workflow" icon="list-checks" href="/en/guides/build-a-tms-plugin/full-integration-workflow">
    Apply these safeguards to the full production lifecycle.
  </Card>

  <Card title="Quick Start" icon="rocket" href="/en/guides/build-a-tms-plugin/quick-start">
    Build a baseline flow, then harden using this guide.
  </Card>
</CardGroup>