Appearance

Download as .md

Validation Errors ​

Written by Rohman Beny Riyanto

A rejected request comes back as one of two genuinely different shapes - telling them apart is what lets FE show a proper "fix these fields" form instead of one generic toast for everything. Full code list is on Response Codes; this page is about which one fires when, and what each shape actually gives you to work with.

431 - per-field validation failed ​

Fires when one or more fields fail their own rule (required, email, min=8, oneof=..., etc - the exact rule for every field is shown in each endpoint's Request fields table on the API Reference pages, in the Validation column).

json
{
  "response_code": "431",
  "response_text": "Validation error",
  "errors": [
    { "field": "email", "message": "email is required" },
    { "field": "password", "message": "password must be at least 8 characters" }
  ]
}

FE handling: errors is always an array, can contain more than one entry (every failing field is reported in one response, not one-at-a-time). Map each field to the matching form input and show message right next to it.

082 - a required field is structurally missing ​

Different from 431 - this fires earlier, before per-field validation even runs, when the request is missing something the request wrapper itself needs (e.g. the top-level command/query key - most endpoints require it, but a few don't; see the > note under each endpoint's Request fields table for whether this applies to it).

json
{
  "response_code": "082",
  "response_text": "Required field is missing",
  "error_details": {
    "error": "CLIENT_ERROR",
    "detail": "...",
    "path": "/v2/..."
  }
}

FE handling: no errors array here - this is a flat, whole-request problem (usually a client bug, like forgetting the command wrapper), not something a form should ever surface to an end user field-by-field. If you're seeing this in production against a real form submission rather than while writing the integration, the request body is being built wrong somewhere.

The one-line version for an interceptor ​

js
if (body.errors) {
  // 431 - per-field, safe to show inline on the form
  body.errors.forEach(({ field, message }) => showFieldError(field, message));
} else if (body.error_details) {
  // 082 (or any other flat error) - whole-request problem, not per-field
  showGenericError(body.response_text);
}