Skip to main content
Every Soap API error is a JSON object, except the framework’s 400 below when you don’t send Accept: application/json. Branch on the HTTP status and, where the error has one, its code, never on the wording: the messages are written for people and can change.

The error body

Two answers come from the web framework before Soap reads the request, so they have no hint or code: a malformed body sent with Content-Type: application/json is a 400, {"status": 400, "error": "Bad Request"} when you send Accept: application/json and an HTML page otherwise, and a path the API does not serve is {"status": 404, "error": "Not Found"}.

Statuses

Authentication failures (a missing or invalid API key or client secret) are described in Authentication.
Always send Content-Type: application/json and Accept: application/json with a request body. With Accept: application/json, the framework’s 400 above comes back as JSON instead of an HTML page.

Handling them

  • 401: send an active API key as Authorization: Bearer key_.... Retrying doesn’t help.
  • 403: contact Soap support. Retrying doesn’t help.
  • 422: fix the request; sending it again unchanged gets the same answer. Read error to find the field; each endpoint’s page in the API reference lists its rules.
  • 404 for a switched-off endpoint: ask Soap to enable it for your account. Retrying doesn’t help.
  • 500, or no answer at all: a read (GET) is safe to retry. Before you retry a create, check whether the first attempt went through. Customers are unique by email, phone_number and internal_id, so look the customer up with Search Customers. A repeated POST /api/v1/checkouts makes a second checkout; the unused one expires unpaid.
  • Treat the HTTP status and code as the machine-readable part of an error, and error and hint as text for your logs.