Errors

A failed request answers with a 4xx or 5xx status and a JSON body. Every body has an error string, written for a person; most also carry a code, stable and meant for your code. Branch on the status and the code, never on the error text.

403

{ "code": "api_key_workspace_mismatch", "error": "This API key belongs to another workspace." }

Status codes

Status	Meaning
`400`	The request is malformed: see Validation errors.
`401`	The API key is missing, invalid, revoked or expired. See Authentication.
`402`	A plan limit refused the request: see Quota errors.
`403`	The key's role lacks a permission, or the route is not for keys.
`404`	No such resource in this workspace. A resource of another workspace answers `404` too: the API never says whether it exists.
`409`	The request conflicts with the current state: a slug or hostname already taken, a deployment no longer queued.
`411`	The request has a body but no `Content-Length` header.
`413`	The request body is too large: 40 MB for creating a deployment, 1 MB everywhere else.
`422`	The request is well formed but breaks a rule, such as a domain redirecting to a domain of another project.
`429`	Too many requests: wait for the `Retry-After` header's number of seconds.
`5xx`	Something failed on Hiraiship's side. Retrying later is safe for reads. A `500` carries a `requestId`: quote it to support.

Validation errors

A body, path or query that doesn't match the route's schema gets a 400 listing every problem, with the path of the field at fault:

400

{
  "error": "validation_failed",
  "details": [
    { "path": ["slug"], "message": "lowercase letters, digits, and hyphens only", "code": "invalid_string" }
  ]
}

Quota errors

A 402 means your plan doesn't allow what you asked: more builds than its queue holds, a build machine it doesn't include, a custom domain past the included ones, a spend limit reached. The body says which limit, and how far you are:

402

{
  "outcome": "quota_exceeded",
  "code": "quota_exceeded",
  "quota": "queued_builds",
  "limit": 10,
  "used": 10,
  "planId": "standard",
  "error": "Your Standard plan runs 2 builds at a time and lets 10 wait — 10 already are. Wait for one to finish, or upgrade your plan."
}

quota is one of the limits listed in Limits. Retrying won't help until something changes: a build finishes, the period ends, or the plan changes.

Codes

`code`	Status	Meaning
`api_key_invalid`, `api_key_revoked`, `api_key_expired`	`401`	See Authentication.
`api_key_forbidden_route`	`403`	The route is for people: members, keys, billing, GitHub.
`api_key_workspace_mismatch`	`403`	`X-Hiraiship-Workspace` names another workspace.
`project_disabled`	`403`	Hiraiship disabled the project; it can't be deployed.
`quota_exceeded`	`402`	A plan limit: see above.
`rate_limited`	`429`	Too many requests or project creations: wait `Retry-After` seconds.
`length_required`	`411`	Send the body with a `Content-Length` header.
`payload_too_large`	`413`	The body is over the route's limit.
`internal_error`	`500`	Something failed on Hiraiship's side; `requestId` identifies it.

A 403 for a missing permission has no code; it names the permission instead (see Roles).