Validation Errors
Validation problems generally mean required business data is missing, inconsistent, or not usable for the operation — malformed JSON, a missing required field, an invalid enum value, or an invalid identifier format.
Verified status codes
| Situation | Status |
|---|---|
Missing, empty, or whitespace-only required field on token exchange (apiKey) or refresh/revoke (refreshToken) | 422 |
Invalid Create Order request (e.g. missing address field, empty shipments) | 400 |
| Invalid Update Order Status request | 400 |
| Invalid Rate request | 400 |
Invalid Label purchase request (e.g. unusable rate id) | 400 |
Malformed X-SubAccount-Id (not a GUID) | 400 |
The public contract's error envelope (errors[].code/message) is the same
shape across every operation — see
Error Handling. Branch on code, not on
message: code is the machine-readable identifier, while message is
human-readable prose whose wording may change and must not be parsed.
Validation codes are namespaced Validation.*, and some are composed at
request time from the field they concern — a missing field produces
Validation.<FieldName>Required and an invalid one
Validation.<FieldName>Invalid. That structure is usable, but it is not a
finite enum and the contract publishes no exhaustive list. Match the codes your
client handles, read the field name out of the code when you need to attribute
the problem to an input, and fall back on the HTTP status for everything else.
Use message for logs and operator-facing diagnostics only.
Recover safely
Inspect the relevant Order, Shipment, address, or parcel data in your client. Correct the data and resubmit only after the underlying issue is resolved. Validation issues normally need correction rather than a repeated identical request — resending the same invalid payload will fail the same way.
For the workflow context, see Order-to-Label Workflow and Create an Order for the exact required fields.