Errors

Nucleo uses standard HTTP status codes. Anything in the 2xx range succeeded; 4xx means the request must change before it can succeed; 5xx means something went wrong on our side.

JSON APIs answer errors with a message and, for validation errors, an errors object with one entry per field:

{
  "message": "The country field is required. (and 1 more error)",
  "errors": {
    "country": ["The country field is required."],
    "qty": ["The qty field must be at least 1."]
  }
}

Some APIs add a machine-readable code or error next to the message (for example origin_not_allowed on the delivery promise or too_many_attempts on the returns lookup). Branch on the code, never on the text of message: the text can be reworded.

The OAuth endpoints follow RFC 6749 and answer {"error": "invalid_grant", "error_description": "…"}. The FFW warehouse interface answers in XML; its reference shows the exact envelopes.

Retrying is safe where the API makes it safe, and each reference page says so:

• Collector — give every event a uid: an event already received is counted in duplicates and never stored twice.
• Tracking webhook — an event identical to one already stored is ignored.
• Warehouse interfaces — repeated acknowledgements, shipments with the same tracking, stock levels and return outcomes have no double effect.
• Reads (GET) are always safe to retry.

For every other write, check the outcome (for example look the return up) before sending the same request again after a timeout.