Missing resources now return 404
Missing resources now return 404
Asking for a resource that does not exist previously returned 400 on most endpoints. It now returns 404, which is what the API reference has always documented.
The response body is unchanged. The code field still identifies what was missing — CounterpartyNotFound, WalletNotFound, PaymentNotFound, UserNotFound, ChallengeNotFound — so integrations that branch on code need no changes. Only the HTTP status differs.
Where this applies
Every endpoint that can report a missing resource, including:
| Endpoint | Code |
|---|---|
GET, PATCH, DELETE /api/v1/counterparties/{counterpartyId} | CounterpartyNotFound |
GET, POST /api/v1/counterparties/{counterpartyId}/payouts | CounterpartyNotFound |
GET /api/v1/wallets/{walletId} | WalletNotFound |
GET /api/v1/wallets/{walletId}/balance | WalletNotFound |
GET /api/v1/wallets/{walletId}/transactions/{transactionId} | TransactionNotFound |
GET /api/v1/users/{userId} | UserNotFound |
POST /api/v1/users/{userId}/disclosures/kyc | UserNotFound |
POST /api/v1/payments/{paymentId}/cancel | PaymentNotFound |
PATCH, DELETE /api/v1/rewards/{rewardId} | NotFound |
POST /api/v1/users/{userIdentifier}/identity-verification/challenges | UserNotFound |
POST /api/v1/users/{userIdentifier}/identity-verification/challenges/{challengeId}/submissions | ChallengeNotFound |
POST /api/v1/users/{userIdentifier}/identity-verification/profile-updates | UserNotFound, ChallengeNotFound |
External transactions and linked accounts report their own missing resources the same way, with their own code.
Endpoints addressed by id under /payments, /payment-intents, /webhooks, and /webhook-events already returned 404 for an unknown id and are unchanged.
Every operation in the API reference now lists the errors it can return.
What has not changed
Validation errors keep their statuses. A malformed identifier is still 400, and codes such as MultipleWalletsFound, InvalidWalletState, WalletNotIssuable, and KycStatusNotFound are unaffected — a 400 that means "this request was wrong" has not become a 404.
Authentication errors
A request with a missing or unrecognized client secret still returns 401. Its code changes from NotFound to Unauthorized, and its title from RequestClientNotFoundException to ClientNotAuthenticatedException. The old code described an authentication failure as a missing resource, which was misleading.
What to check
If you match on HTTP status alone to detect a missing resource, update those branches to 404. If you treat 400 as "bad request, do not retry", missing resources no longer land in that bucket. Matching on code continues to work unchanged.