Skip to main content
All API errors return a consistent JSON envelope.

​
Error shape

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Validation failed.",
    "errors": []
  }
}
FieldTypeDescription
error.typestringError category
error.codestringMachine-readable code (optional)
error.messagestringHuman-readable description
error.errorsarrayField-level validation details (optional)

​
Error codes

CodeDescription
invalid_credentialsWrong client_id or client_secret
insufficient_scopeToken lacks required permission
api_key_disabledAPI credential has been disabled
auth_rate_limitedToo many failed auth attempts
rate_limitedAPI request rate limit exceeded
validation_failedRequest body or query validation failed
idempotency_in_progressDuplicate idempotency key while request is processing
version_mismatchAPI version conflict (reserved for future use)

​
HTTP status mapping

StatusWhen
400Invalid JSON, validation errors, unsupported API version at auth
401Missing or invalid bearer token, invalid credentials at auth
403Insufficient scope, disabled API credential
404Resource not found
409Idempotency conflict (request in progress)
429Rate limit exceeded
500Internal server error

​
Validation errors

When request validation fails, the errors array contains Zod-style field details: 
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Validation failed.",
    "errors": [
      {
        "code": "too_small",
        "minimum": 1,
        "type": "array",
        "inclusive": true,
        "exact": false,
        "message": "At least one scope is required",
        "path": ["scopes"]
      }
    ]
  }
}

​
Response headers on errors

Error responses still include ST-Api-Version when the API version is known from the token or auth flow.