docs: enrich fx-account API reference with per-endpoint error examples#5
Merged
marioalvial merged 2 commits intomainfrom Apr 15, 2026
Merged
Conversation
Adds specific error examples to each of the 12 fx-account endpoints
using OpenAPI 3.0 plural `examples:` (Mintlify renders as a dropdown).
Promotes four previously implicit error cases to explicit status codes
(addUbo 409, listUbos / getUbo / removeUbo 422).
Also consolidates docs structure:
- Merge "Open a BRL account" + "Open a crypto account" into a single
"Open a multi-currency account" journey. Accounts are multi-currency
(one account, multiple assets) so the split was misleading.
- Replace stale create-account payload with the real OpenAPI contract
(assets: [{code, isVirtual}], owner discriminator).
- Remove the low-signal sandbox-note callout from all journey pages.
- Link the navbar logo to the docs root instead of a dead URL.
Depends on tracefinance/fx-account#84 for the
`UBOS_NOT_ALLOWED_FOR_INDIVIDUAL` error code. Hold merge until that
lands; otherwise docs will show `UBOS_` while the live API still
emits `U_B_OS_`.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Replaces two dead card links (open-brl-account, open-crypto-account, both removed in this PR) with a single card pointing at the new open-multi-currency-account journey — matching the link rename already applied to quickstart and the other journey pages. Unblocks the Mintlify build validation and link-rot checks.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Per-endpoint error examples for the fx-account API reference, plus cleanup found along the way.
API Reference (main change)
Enriches
apis/fx-account/openapi.ymlwith specific error examples per endpoint, rendered in Mintlify as a dropdown selector. Mapped from actual exceptions infx-account/core:INVALID_TAX_ID,UNSUPPORTED_ASSET,INVALID_DATA,UBOS_NOT_ALLOWED_FOR_INDIVIDUALINVALID_UUID,RESOURCE_NOT_FOUNDMISSING_DOCUMENTS_FOR_REVIEW(×2),NO_PROVIDER_ACCOUNT_REQUIRES_ANALYSISINVALID_UUID,RESOURCE_NOT_FOUNDEMPTY_FILE,MISSING_MULTIPART_FIELD,INVALID_UUID,RESOURCE_NOT_FOUNDINVALID_TAX_ID,INVALID_DATA,DUPLICATE_UBO,UBOS_NOT_ALLOWED_FOR_INDIVIDUAL,ACCOUNT_NOT_MODIFIABLE,INSUFFICIENT_OWNERSHIPUBOS_NOT_ALLOWED_FOR_INDIVIDUALRESOURCE_NOT_FOUND(×2),UBOS_NOT_ALLOWED_FOR_INDIVIDUALINVALID_TAX_ID,RESOURCE_NOT_FOUND(×2), plus 4× 422 variantsRESOURCE_NOT_FOUND(×2),UBOS_NOT_ALLOWED_FOR_INDIVIDUAL,ACCOUNT_NOT_MODIFIABLE,APPROVED_UBOEMPTY_FILE,MISSING_MULTIPART_FIELD,INVALID_UUID,RESOURCE_NOT_FOUND(×2)Journey consolidation
open-brl-account+open-crypto-account→ singleopen-multi-currency-accountjourney. Accounts are multi-currency (one account, many assets) so the split was misleading.ownerwithtypediscriminator,assets: [{code, isVirtual}]).Config cleanup
<SandboxNote />callout from all journey pages (low-signal;{{sandboxUrl}}in curl examples is already obvious).snippets/sandbox-note.mdx.logo.hreffromdocs.jsonso the logo links to the docs root instead of a dead URL.CLAUDE.mdsnippet list.Dependency
Draft pending tracefinance/fx-account#84, which renames
UBOsNotAllowedForIndividualException→UbosNotAllowedForIndividualExceptionso the derived HTTP error code becomesUBOS_NOT_ALLOWED_FOR_INDIVIDUAL(what this PR documents) instead of the currentU_B_OS_NOT_ALLOWED_FOR_INDIVIDUAL. Flip this PR to Ready after fx-account#84 is merged.Test plan
yaml.safe_loadon the OpenAPI succeeds — 8 paths, all intactnullableissues unrelated)mint devsmoke test — confirm dropdown examples rendermint broken-links— confirm the journey link renames didn't break anythingOut of scope (follow-ups)
listAccountsfor filter parsing errors (same reason).nullable: trueschema entries (OpenAPI 3.1 compliance).