# Draft: l10n(pt-BR): translate the error-handling section [DOC-6059]

## 1. What this is

All three `api-docs/error-handling` pages: **8,687 words**, 21 sections. First batch of the
bulk-translation phase after `financial-instruments.md`.

- Branch: `l10n/pt-br/error-handling`, based on `l10n/pt-br/bootstrap` at `310ef3da3`.
- English unmodified.


## 2. Scope of this MR

Three pages translated in full, added to `scope.json`, manifest regenerated.

| Page | Words | Sections |
|  --- | --- | --- |
| `api-errors.md` | 7,508 | 14 |
| `api-payment-failures.md` | 619 | 2 |
| `payments-direct-api-errors.md` | 560 | 5 |


## 3. Method

`api-errors.md` is 2,274 lines of error tables with heavy repetition: `Internal server error` appears 92 times, one description 89 times. As with `financial-instruments.md`, I
extracted every distinct translatable string (**306**, against 1,404 total segments),
translated each once, and applied the map deterministically. The transform **fails loudly
on unmapped lines** and reported **0 unmapped** across all 2,275 lines.

262 further distinct strings were bolded error-code cells (`**AUTH_001**`) and needed no
translation.

## 4. English source reference

Translated against `bootstrap` at `310ef3da3`.

## 5-6. OpenAPI render check / structural preservation

Spec out of scope (!1459). Structure verified mechanically:

|  | EN | pt-BR |
|  --- | --- | --- |
| Sections | 14 / 2 / 5 | 14 / 2 / 5 |
| Lines | 2274 / 30 / 71 | 2274 / 30 / 71 |
| Structural kind per line | — | **0 mismatches** |


Error codes, enums and statuses are preserved exactly: `AUTH_` 11, `USR_` 123, `SYS_` 115,
`CFG_` 24, `USER_ERROR` 118, `SYSTEM_ERROR` 116, `CONFIGURATION_ERROR` 27, `AUTH_ERROR` 6,
`NOT_FOUND` 5 — identical counts on both sides. The JSON example block is byte-identical.
`$env` vars preserved.

## 7. Terminology

Consumes the termbase. `payment rail`, `tenant`, `timestamp`, `endpoint`, `schema` and
`backoff` all at English parity with the source. **Zero** occurrences of `trilho`,
`meio de pagamento` or `rede de pagamento`.

## 8. Reviewer attention items

1. **New convention set here, please confirm.** English sentences that *begin* with
`{% $env.PUBLIC_VAR_RPD %}` are translated **without a leading article** — so
" retorna respostas..." rather than "O  retorna...". Reason:
the pipeline classifies a line starting with `{%` as structural rather than prose, so
adding "O " changes the line's kind, breaks positional pairing, and silently drops that
line from the translation memory forever. There are 5+ more such sentences in
`introduction`, so this wants settling now. If Luis prefers the article, the cost is
those lines never harvesting; that is a real but acceptable trade if the reading is
better.
2. **Error titles are UI-adjacent.** Titles like "Saldo insuficiente" and "Fatura vencida"
may surface in partner tooling. Worth a read for whether they match what a Brazilian
operations user would expect.
3. **`USR_152` and `USR_173` have identical English** and are translated identically. Same
for `USR_062`/`USR_201`, `USR_066`/`USR_204`, `USR_067`/`USR_205`. Deliberate.
4. **Kept English**: `Cdtr.Nm`, `Cdtr.StrdNm`, `sender_End_To_End_Id`, `PstlAdr.AdrLine`
(ISO 20022 field names), and JSON example values.
5. **`payout` is rendered as plain "pagamento", not the Verified termbase target
"pagamento ao beneficiário".** 6 occurrences here, 73 across the translated set.
Flagging rather than sweeping, because the termbase contradicts itself and the
approved text: the pilot renders "payout partner" as "parceiro de pagamento", and the
termbase's own `payout method` entry is "método de pagamento", both dropping "ao
beneficiário". Rendering it in full would also read heavily in table cells repeated
dozens of times. **Please confirm which form you want**; whichever you pick I will
apply it across the whole translated set in one pass, and add it to the QC gate.


## 9-11. Screenshots / source defects / config

No screenshots. No source defects found. No config changes.

## 12. Translation memory

`tm.jsonl` unchanged. **No harvest** (§8.3, handoff §4.10). Dry run: **777 records
available** on approval, 0 alignment problems.

## 13. Pipeline and QC gates

Both quality gates pass on this batch:

- `qc-structure.mjs`: **no structural findings** across all 8 translated files.
- `qc-terminology.mjs`: clean apart from the `payout` question in §8.5.
- `manifest.json`: **8 files, 109 sections**, drift **green**.
- `selftest.mjs`: all checks passed.
- Alignment: 0 kindMismatch, 0 lineCountMismatch, 0 cellCountMismatch, 0 markdocMismatch.


## 14. Review gate

Do not self-approve, mark ready, merge, or resolve discussions. Portuguese; needs native
review. This batch is a good spot-check candidate: the error titles are short, high-volume,
and user-visible.

## 15. Open items

`integration-resources` is next: 71 pages, 25,041 words, 1,769 distinct segments at 2.8x
repetition — the single largest and most formulaic block remaining.