Errors

Every error of the API has the same format: an HTTP status, and an error object with a code and a message.

// 409 Conflict
{
  "error": {
    "code": "key_taken",
    "message": "Another license of the product already uses this key"
  }
}

• code is stable: branch on it in your code.
• message explains the error to a developer, in English. It can change at any time: don’t parse it, and don’t show it to your customers as is.

Each endpoint lists the codes it can return in the API reference.

Validation errors

An invalid path, query parameter or body answers 422, not 400, with the validation_error code and an issues array, giving the path and message of each invalid value:

// 422 Unprocessable Entity
{
  "error": {
    "code": "validation_error",
    "message": "Invalid request",
    "issues": [
      { "path": ["email"], "message": "Invalid email address" },
      { "path": ["maxVersion", "lockMinorAt"], "message": "The minor version can't be locked before the major version" }
    ]
  }
}

path lists the keys leading to the value, numbers for the positions in an array. Every invalid value is listed, not only the first one.

Status codes

Common codes

These can be returned by any endpoint.

Codes by resource

Products

Policies

Customers

Licenses

Validating a key has its own codes: see handling validation errors.

Releases

Stripe integration

Billing

These endpoints only work from the app.

Handling errors in your code

• Branch on code, never on message, and treat unknown codes like their status.
• Retry 500 and 502 a few times, waiting longer each time, and network errors too. Retry 429 after the Retry-After seconds. Don’t retry other errors: they’ll fail the same way.
• Creating twice: when a request creating a license times out, it may have been created anyway. List the customer’s licenses before retrying, or create it with your own key, so the retry fails with key_taken rather than creating a second license.