Skip to content

Getting started

Errors

The one shape every error has, how to retry, and every error code.

A failed call answers with an HTTP status of 400 or more and one shape, whatever went wrong:

Error
{
  "error": {
    "type": "invalid_request_error",
    "code": "VALIDATION_ERROR",
    "message": "tracks[0].title: Required",
    "details": [{ "path": "tracks[0].title", "message": "Required", "code": "invalid_type" }],
    "requestId": "req_…"
  }
}
FieldWhat it is
typeThe family: invalid_request_error, authentication_error, permission_error, not_found_error, conflict_error, idempotency_error, rate_limit_error, service_unavailable_error, api_error
codeA stable code to branch on; listed below
messageA sentence for people; it may change, so never match on it
detailsWhen there is more: each invalid field for VALIDATION_ERROR, the issues for RELEASE_SUBMISSION_INVALID
requestIdAlso in the X-Request-Id header; send it to support with any question

Error codes#

These are the codes the API layer returns. An endpoint can also pass on a code from the workspace rule behind it (for example INVALID_RELEASE_STATUS); the reference lists them with each endpoint.

StatusCodeWhat it means
401API_KEY_REQUIREDNo key was sent. Send it as Authorization: Bearer <key>.
401INVALID_API_KEYThe key is malformed, unknown or does not match.
401API_KEY_REVOKEDThe key was revoked. Create a new one in the API tab.
401API_KEY_EXPIREDThe key passed its expiry date.
403API_KEY_PAUSEDStillmore Group paused the key. Contact support.
403API_KEY_OWNER_INACTIVEThe member the key acts for lost access to the organization. An owner or admin can take the key over.
403API_ACCESS_DISABLEDAPI access is not turned on for this organization.
400INVALID_ORGANIZATION_HEADERThe Stillmore-Organization header must be an organization id from GET /v1/organizations.
403SUB_LABELS_NOT_ALLOWEDThe key may not act for sub-labels. An owner or admin allows it on the key in the API tab.
403SUB_LABEL_NOT_ALLOWEDThe organization in Stillmore-Organization is not a sub-label below the key's organization, or the member the key acts for can't open it.
403SANDBOX_ONLYSimulations run in the sandbox only; call them with a test key (sm_test_…).
400SANDBOX_NO_SUB_LABELSTest keys work in the organization's sandbox only; leave out the Stillmore-Organization header.
401OAUTH_TOKEN_INVALIDThe OAuth access token is malformed, unknown or revoked.
401OAUTH_TOKEN_EXPIREDThe OAuth access token is over an hour old. Get a new one with the refresh token.
401OAUTH_CONNECTION_REVOKEDThe organization disconnected the app, or the app was deleted. It has to be connected again.
403OAUTH_APP_SUSPENDEDStillmore Group suspended the app.
403OAUTH_MEMBER_INACTIVEThe member who connected the app lost access to the organization. An owner or admin can connect it again.
403IP_NOT_ALLOWEDThe request came from an address the key does not allow.
403INSUFFICIENT_SCOPEThe key lacks the scope this endpoint needs.
403OWNER_PERMISSION_MISSINGThe member the key acts for no longer holds the permission this endpoint needs.
429TOO_MANY_FAILED_ATTEMPTSToo many requests with a wrong key came from this address. Wait and try again.
429RATE_LIMITEDThe key or the organization sent too many requests this minute. Retry after Retry-After seconds.
400VALIDATION_ERRORThe request did not pass validation; details lists each field.
400INVALID_JSONThe body is not valid JSON.
413PAYLOAD_TOO_LARGEThe body is larger than 1 MB. Files are uploaded separately.
415UNSUPPORTED_MEDIA_TYPESend JSON with Content-Type: application/json.
400INVALID_IDAn id in the request is not a valid identifier.
404ROUTE_NOT_FOUNDNo endpoint answers at this method and path.
400INVALID_CURSORPass nextCursor from the previous page as it is.
412REVISION_MISMATCHThe record changed since you read it (If-Match). Read it again and retry.
409EXTERNAL_ID_IN_USEAnother record of the same kind in your organization already has this externalId.
409UPC_IN_USEAnother release already carries this UPC.
409LABEL_ARCHIVEDReleases can't be added to an archived label.
403API_PAYOUTS_OFFPayout requests through the API are off. An owner or admin turns them on in Workspace › API › Settings.
429SUBMISSION_LIMIT_REACHEDThe organization used today's submissions through the API; the limit resets at midnight UTC.
422RELEASE_SUBMISSION_INVALIDThe release misses what submission needs; details.issues lists each field (GET …/checks shows the same before submitting).
409UPLOAD_NOT_RECEIVEDComplete was called before the file arrived at the upload address. Finish the PUT first.
422ARTWORK_CMYKThe cover is CMYK; stores take RGB covers only.
400IMPORT_URL_NOT_ALLOWEDImports take public http or https links without credentials in them.
422IMPORT_FAILEDThe link could not be downloaded, or what came back was not usable (shown on the import).
422IMPORT_TOO_LARGEThe file at the link is larger than the limit for its kind.
422IMPORT_TIMED_OUTThe download took too long; upload large files with the upload endpoints.
410STATEMENT_VOIDStillmore Group withdrew the statement after publishing it; a corrected statement follows. It stays listed with status VOID, without its lines.
400IDEMPOTENCY_KEY_INVALIDThe Idempotency-Key header must be 1 to 255 visible characters.
422IDEMPOTENCY_KEY_REUSEDThe Idempotency-Key was already used with a different request.
409IDEMPOTENCY_IN_PROGRESSA request with this Idempotency-Key is still running. Retry shortly.
503MAINTENANCEThe platform is being updated. Retry after Retry-After seconds.
503MAINTENANCE_READ_ONLYReads work, changes are paused while the platform is updated.
503DATABASE_UNAVAILABLEA short outage on our side. Retry after Retry-After seconds.
500INTERNAL_ERRORSomething failed on our side. Retry with the same Idempotency-Key, or send the request id to support.