Errors

Status codes and error response shape.

Error response shape

Non-2xx responses return JSON:

{
  "error": "machine_readable_code",
  "message": "Human-readable description.",
  "requestId": "req_abc123..."
}

• error is stable — code your branching logic against this.
• message is for humans; we may rephrase it without notice.
• requestId is what you mention to support when something is broken.

Status codes

Code	When
200 OK	Successful read
201 Created	Resource created
202 Accepted	Async operation queued (e.g. build dispatch)
204 No Content	Successful write with no body
400 Bad Request	Invalid input
401 Unauthorized	Missing or invalid token
403 Forbidden	Token lacks permission for this action
404 Not Found	Resource doesn’t exist or you can’t see it
429 Too Many Requests	Rate-limited; see Retry-After header
500 Internal Server Error	Bug on our side — include requestId when reporting

Common error codes

Code	Description
invalid_token	Token is malformed, revoked, or expired.
insufficient_scope	Token doesn’t have the required permission.
validation_failed	Input failed schema validation.
engine_not_found	Requested ueVersion is not supported.
repo_not_accessible	GitHub App lost access to the repo.
perforce_auth_failed	Perforce credentials rejected.

Rate limiting

When rate-limited:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

Wait Retry-After seconds before the next request.