Error Handling

How the API signals failure, what the common HTTP statuses mean, and how to troubleshoot.

Error response shape

Errors use the same envelope as success responses, with success: false and a descriptive message:

{
  "data": null,
  "success": false,
  "message": "Validation failed: financialInstitutionId is required",
  "timestamp": "2026-06-03T10:15:30.000Z"
}

📘 Note

The exact error body fields (e.g. whether an errorCode or errors[] array is included) are To be confirmed — the source collection does not capture populated error responses. Always branch on the HTTP status code and the success flag.

Common HTTP status codes

Status	Meaning	Likely cause	Recommended action
200	OK	Request succeeded.	Process `data`.
201	Created	Resource created.	Read the new id from `data`.
400	Bad Request	Missing/invalid fields, malformed JSON, wrong content type.	Validate the body against the field reference; check required fields and types.
401	Unauthorized	Missing/expired/invalid token.	Re-authenticate or refresh the token; ensure `Authorization: Bearer` is set.
403	Forbidden	Authenticated but lacks the required role/module action.	Check the user's role and module entitlements (RBAC).
404	Not Found	Unknown id, code, or path (watch singular/plural paths).	Verify the id and the exact endpoint path.
409	Conflict	Duplicate entity (e.g. an FI or key that already exists).	Fetch the existing record or update instead of create.
422	Unprocessable Entity	Semantic validation failure.	Review business constraints for the resource.
429	Too Many Requests	Rate limiting (if enforced at the gateway).	Back off and retry with jitter. See Security → Rate limiting.
500	Server Error	Unhandled server-side failure.	Retry idempotent reads; capture `x-correlation-id` and contact support.
503	Service Unavailable	A downstream service/core is unreachable.	Check `POST /v1/onboarding/healthstatus` and retry later.

❗ Status set is representative

The status codes above are the conventional set for this style of API. The definitive list returned by each endpoint is To be confirmed against the service.

Platform error-code catalog

The platform maintains a catalog of business error codes, retrievable at runtime:

POST /v1/onboarding/error-codes/list?page=0&size=150
Authorization: Bearer <JWT_TOKEN>

This returns a paged list of { code, message, ... } entries. The concrete codes and messages are not enumerated in the source collection and are therefore To be confirmed; query this endpoint in your environment for the authoritative set.

Troubleshooting checklist

401 right after login? Confirm you sent the token from the login response's data field (not the whole envelope), prefixed with Bearer .
404 on a write? Re-check singular vs plural paths (/financialInstitution to create, /financial-institutions to update; /transaction-capability vs /transaction-capabilities; terminal keys at /v1/terminal-key).
400 with valid-looking JSON? Ensure Content-Type: application/json; for the SSO token endpoint use application/x-www-form-urlencoded; for sub-tenant creation use multipart/form-data.
Intermittent 5xx? Check service health and include the x-correlation-id you sent when raising a support ticket.

💡 Tip

Always send a unique x-correlation-id. It is echoed in responses and logs, turning a vague "it failed" report into a traceable request.