Error Handling

Embarc uses consistent HTTP status codes and a predictable JSON structure for error responses. Understanding that structure makes it easier to surface meaningful messages in your UI.

Status Codes at a Glance

Status	When it appears	Typical cause
`200 OK`	Successful commands or queries	Resource created/updated/fetched without issues
`400 Bad Request`	Validation or business rule failure	Missing mandatory fields, invalid loan state transitions, malformed JSON
`401 Unauthorized`	Authentication failure	Missing/expired token or Basic credentials
`403 Forbidden`	Authenticated but not allowed	Lacking the required role/permission
`404 Not Found`	Resource lookup failed	Wrong customer ID, loan ID, or tenant
`409 Conflict`	Command can’t proceed because of current state	Attempting to disburse an already-closed loan, duplicate external IDs
`500 Internal Server Error`	Unexpected server exception	Embarc bug or infrastructure issue. Contact support with correlation IDs

Error Payload Shape

{
  "developerMessage": "The request was invalid. This typically will happen due
to validation errors which are provided.",
  "httpStatusCode": "400",
  "defaultUserMessage": "Validation errors exist.",
  "userMessageGlobalisationCode": "validation.msg.validation.errors.exist",
  "errors": [
    {
      "parameterName": "loanType",
      "developerMessage": "The parameter `loanType` is mandatory.",
      "defaultUserMessage": "The parameter `loanType` is mandatory.",
      "userMessageGlobalisationCode":
"validation.msg.loan.loanType.cannot.be.blank"
    }
  ]
}

Key fields to surface:

defaultUserMessage — human-readable explanation suitable for UI.
errors[] — per-field messages when relevant.
httpStatusCode — mirrors the actual HTTP status code for quick triage.

Handling Tips

Treat defaultUserMessage as the primary message for end users; fall back to developerMessage when localising isn’t an option.
When errors[] is present, iterate through it to highlight individual field issues (e.g., inputs on a loan origination screen).
Log the entire payload (with correlation or request IDs) so our support team can trace issues quickly.