Getting started

Errors

Starmile uses conventional HTTP status codes. 2xx means success; 4xx means the request was rejected — the JSON body explains why.

200 / 201Success

The request succeeded. 201 is returned when a resource is created.

401Unauthorized

Missing, invalid or expired bearer token, or client authentication failed at /oauth/token. Obtain a fresh token.

403Forbidden

The Partner API is not enabled for the organization, or your credential has been revoked. Contact your Starmile partner.

422Unprocessable entity

Validation failed. The errors object lists each invalid field.

404Not found

The referenced resource (e.g. a service_id) does not exist.

Validation errors

A 422 response includes a top-level message and an errors map keyed by field name, each with an array of messages — suitable for surfacing inline in your integration.

{
  "message": "The items field is required.",
  "errors": {
    "items": ["The items field is required."]
  }
}

Retries (PHP SDK)

The PHP SDK automatically retries safe (GET) requests on transient failures (network errors, 429, 5xx) with exponential backoff, honouring Retry-After. Writes such as creating an order are neverretried automatically, so a flaky response can’t create a duplicate. To retry a write, opt in per call with retry():

// Retry this create up to 3 times (200ms base backoff):
$starmile->retry(3, 200)->orders()->create($order);

// Custom rule — also retry a specific conflict:
$starmile
    ->retry(4, 200, fn ($e) => $e->getStatusCode() === 409)
    ->events()->report($event);