Errors

The SparkLayer APIs use standard HTTP status codes: 2xx for success, 4xx when the request needs fixing, and 5xx when something went wrong on SparkLayer's side. Most errors include a JSON body that explains the problem.

Error body

Error bodies follow the RFC 7807 problem details (opens in a new tab) format:

{
  "title": "invalid-request-contents",
  "status": 400,
  "detail": "Unable to validate request contents",
  "errors": [
    {
      "code": "keyword-mismatch",
      "message": "<what is wrong with the value>",
      "property": "customer_id"
    }
  ]
}

Some APIs also include "type": "about:blank". Treat the status code as the primary signal, title and errors[].code as more specific detail, and ignore fields you don't recognise.

Status codes

Authentication errors

Errors from /api/auth/token, and errors caused by a missing or invalid token on the Core and Ordering APIs, use OAuth 2.0 error codes (opens in a new tab) as the title:

{
  "title": "invalid_client",
  "status": 401,
  "detail": "Client authentication failed"
}

The Pricing, Purchasing, Stock, Sync Logging and Files APIs return a 401 or 403 problem body with a detail explaining why the token was rejected.

Validation errors

When a request doesn't match the API's schema, the response is a 400 with details of each problem in errors. On the Core and Ordering APIs, and for most requests to the Pricing API, the title is invalid-request-contents. The Core and Ordering APIs use these codes:

The Purchasing, Stock, Sync Logging and Files APIs describe schema problems in detail instead.

Cart errors

The Ordering API returns 422 when it can't process a cart. The title tells you which kind of problem it is:

• cart-error: errors lists codes such as cart-empty, cart-customer-not-found, cart-shipping-rate-handle-unavailable or cart-payment-method-unavailable.
• cart-validation-errors: returned by Complete a cart when the cart has validation errors you haven't chosen to ignore. errors.validation_error_types lists them. Fix the cart, or list the types you accept in ignore_validation_errors, and try again.

Retrying requests

• Retry 5xx responses and 409 conflicts caused by concurrent updates, using exponential backoff.
• On a 401, request a new access token once and retry. If it fails again, check your credentials rather than retrying.
• Don't retry other 4xx responses without changing the request.
• PUT requests that create or replace a record, such as Create or update a purchase, are safe to repeat. Before retrying a POST that creates something, check whether the first attempt succeeded.

Rate limits

SparkLayer doesn't publish fixed rate limits. Design your integration to be gentle and to recover:

• Send changes in batches using the bulk endpoints (for example Update prices across price lists and Update stock levels for multiple SKUs) rather than one request per SKU.
• Run requests one after another, or with a small number in parallel.
• No SparkLayer API returns 429 Too Many Requests today. If you ever receive one, wait before retrying: use the Retry-After header if the response has one, otherwise back off exponentially.