Skip to main content

Errors, Response Codes & Validation

The SDC uses two error shapes: field validation errors (HTTP 400) and operational response codes (in the body/status).

Validation errors (HTTP 400)

When a request fails structural or business validation, the SDC returns HTTP 400 with a modelState array — one entry per invalid field, each carrying one or more 4-digit codes:

400 Bad Request
{
  "message": "Bad Request",
  "modelState": [
    { "property": "items[0].name", "errors": ["2803"] },
    { "property": "payment",       "errors": ["2801"] }
  ]
}
CodeMeaning
2800Field required.
2801List length less than expected (e.g. no items / no payment).
2803Field required (item field).
2804Field length invalid.
2805Field value invalid (bad type, unparseable date/number, unknown enum).
2807Field out of range.

The property path mirrors the request, including array indices — e.g. items[2].quantity, payment[0].paymentType.

Operational response codes

These signal SDC/Secure-Element state rather than a malformed request.

CodeWhereMeaning
0100POST /pin bodyPIN verified.
1300/pin body, /status.gscSecure Element not present / unreadable.
1500/invoices 400 bodyPIN verification required — call POST /api/v3/pin first.
2100/pin bodyPIN incorrect.
2110/pin bodyBlocked, or last attempt withheld to avoid locking the card.
2400/status.gscSecure Element limit reached — audit required.

Missing PIN on sign

400 Bad Request
{ "message": "PIN verification required.", "code": "1500" }

Secure Element / card faults

A card fault during signing (removed card, PIN lock, SE limit) returns HTTP 503 with the message and the 4-digit code, for example:

503 Service Unavailable
"Secure Element limit reached (code 2210)"
  • 400 with modelState — fix the offending field(s) and resubmit; do not retry unchanged.
  • 1500 — prompt for the PIN, call /pin, then resubmit the sale (reuse the same RequestId).
  • 503 (SE fault) — surface the message to the operator; retry the same RequestId once the fault clears (e.g. card reinserted). Idempotency ensures no double-signing.
Back to top