# UJ-006 Surface translation service errors

Audience: AI coding agents first.

- Actor + entry point: WordPress administrator; translation modal at `#/translate-posts/posts`.
- Priority: MUST-HAVE.
- Preconditions: Seed post through WordPress REST API. Fault-inject backend response at HTTP boundary; never mutate DB.
- Test layer: L2.

## Steps

1. Queue translation with invalid key → toast renders backend invalid-key message; modal enters failed state (`admin/src/pages/translate-posts.js:875-882`).
2. Queue with exhausted wallet → visible quota/credits message; no success text.
3. Queue while backend unreachable → visible transport error or `Failed to queue translation`; action remains retryable.

## Failure branches

- `401`: invalidate cached key-valid state and surface error (`docs/contracts/plugin-client-contract.md:58-65`).
- `402`: surface quota exceeded; source content unchanged (`docs/contracts/plugin-client-contract.md:64-65`).
- `429`: surface rate limit; no duplicate job on user retry.
- `500/502/503`: surface temporary server failure (`docs/contracts/plugin-client-contract.md:64-65`).

## Backend touchpoints

`POST /v1/translate`; `POST /v1/jobs`.