Errors

Errors come from two places, with two JSON shapes:

• The gateway at api.hexelstudio.com answers before your request reaches a service: missing or invalid credentials, rate limits, unknown paths, timeouts. Its body is an error object.
• The service that handles the request answers everything else: permissions, validation, plan limits, conflicts. Its body has an error string, sometimes with more fields.

The token service at sts.hexelstudio.com uses a third, OAuth-style shape. See Token service errors.

Most responses, including errors, carry an X-Request-Id header. Include it when you contact support.

Gateway errors

{
  "error": {
    "code": "401",
    "message": "Authentication is required or the provided credentials are invalid."
  }
}

code is the HTTP status as a string. message is meant for people; don't match on it.

A 502 or 504 can also arrive as an HTML page from Hexel Studio's network edge instead of this JSON.

Rate limits

Identity and access endpoints are rate limited per minute, per caller and per organization. A request over a limit gets 429 with the gateway body above and these headers:

For the values and what each scope counts, see Limits.

Service errors

Most service errors have a single error field. It is either a short code, such as forbidden, or a sentence:

{ "error": "forbidden" }

{ "error": "workspace not found" }

If you send X-Organization-Id with an access token for a different organization, the service can't identify you and answers 401 unauthorized or 403 forbidden.

Match on the HTTP status and on the named codes below. Treat other error text as a message for people; it can change.

Named error codes

last_owner and not_org_member also have a message:

{
  "error": "last_owner",
  "message": "the organization must keep at least one owner"
}

Permission errors

A 403 forbidden means the caller's policies don't allow the action in this organization, workspace or environment. Some responses name what is missing.

When an endpoint needs one specific permission, the body can include it as required:

{ "error": "forbidden", "required": "iam:role:write_trust" }

When you try to grant access you don't hold yourself, for example by attaching a policy, the body lists the actions you are missing:

{
  "error": "forbidden",
  "reason": "cannot grant actions the caller does not hold",
  "missing_actions": ["iam:policy:write"]
}

A member-rank refusal is also 403, with a sentence in error, such as "cannot assign role equal or higher than your own". See Members.

To find out why a request was denied, see Test access.

Plan limit errors

{
  "error": "quota_exceeded",
  "quota_key": "workspaces_per_org",
  "limit": 3,
  "current": 3,
  "message": "plan limit reached: this organization can have at most 3 workspaces; upgrade the plan or contact Hexel"
}

See Limits.

Other status codes

The organization-setup response looks like this:

{
  "error": "organization provisioning is pending; retry the same request",
  "org_id": "<org-id>",
  "provisioning_status": "PENDING"
}

Token service errors

The token service (https://sts.hexelstudio.com/token and its other endpoints) answers with an error field and, for some errors, an error_description:

{
  "error": "invalid_grant",
  "error_description": "subject_token was revoked"
}

Other token service errors have a sentence in error, such as "invalid api key", "invalid client credentials", "refresh token expired" or "token revoked". See Authenticate to the API and Tokens.