Errors

Every REST endpoint across both apps returns the same JSON error body for 4xx and 5xx responses. Implementing it consistently matters: the error message is what Alderstone surfaces to users when something fails, and the code is how you (and support) diagnose it.

POST4xx / 5xx

Error body

Every error response includes schemaVersion, error, and code. Validation failures may add details.

Name
schemaVersion
Type
string
Description
Always "1".
Name
error
Type
string
Description
Human-readable message.
Name
code
Type
string
Description
Machine-readable code (see table below).
Name
details
Type
object
Description
Optional field-level validation errors for 422.

Response

4xx / 5xx

{
"schemaVersion": "1",
"error": "Human-readable message",
"code": "VALIDATION_FAILED",
"details": {
  "fieldErrors": { "customerId": ["Required"] }
}
}

Status codes

Name
401
Description
UNAUTHORIZED: missing or invalid Authorization: Bearer header.
Name
403
Description
FORBIDDEN: token valid but not allowed for this operation.
Name
400
Description
INVALID_JSON or BAD_REQUEST: malformed body or unsupported input.
Name
422
Description
VALIDATION_FAILED: schema validation failed; see details.
Name
500
Description
INTERNAL_ERROR: unexpected server failure on the ERP side.

Error codes

Name
UNAUTHORIZED
Type
401
Description
Require Authorization: Bearer {token} on every request.
Name
FORBIDDEN
Type
403
Description
Token is recognized but lacks permission.
Name
INVALID_JSON
Type
400
Description
Request body is not valid JSON.
Name
VALIDATION_FAILED
Type
422
Description
Body failed contract validation; include details when possible.
Name
BAD_REQUEST
Type
400
Description
Well-formed JSON that cannot be processed (e.g. Unknown customer).
Name
INTERNAL_ERROR
Type
500
Description
Unhandled exception; log server-side; return a safe message to the client.

Practical guidance

Write error messages for the operator who will read them in the Alderstone UI, e.g. SKU WIDGET-42 not found in ERP catalogue instead of not found.
Don't swallow upstream ERP failures into empty result arrays; return a 500 with INTERNAL_ERROR (or 400 BAD_REQUEST when the input caused it) so failures are visible instead of looking like missing data.
Authentication failures are covered in detail in Authentication; validation behaviour can be tested in the Developer Sandbox, which returns the same 422 shape as production.