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"] }
 ]
} 
 
 Code Meaning 
 
 2800 Field required. 
 2801 List length less than expected (e.g. no items / no payment). 
 2803 Field required (item field). 
 2804 Field length invalid. 
 2805 Field value invalid (bad type, unparseable date/number, unknown enum). 
 2807 Field 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. 
 
 Code Where Meaning 
 
 0100 POST /pin body PIN verified. 
 1300 /pin body, /status.gsc Secure Element not present / unreadable. 
 1500 /invoices 400 body PIN verification required — call POST /api/v3/pin first. 
 2100 /pin body PIN incorrect. 
 2110 /pin body Blocked, or last attempt withheld to avoid locking the card. 
 2400 /status.gsc Secure 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)" 

 Recommended handling 
 
 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.