Reference

Errors and exit codes

Every error has a stable code, a message and a request ID. The CLI prints errors to stderr and exits with a code that tells scripts what went wrong.

Error format#

json

{
  "error": {
    "code": "CONTRACT_INVALID",
    "message": "request validation failed",
    "retryable": false,
    "request_id": "req_...",
    "details": {}
  }
}

Field	Meaning
`code`	Stable error code. Use it in code, not the message.
`message`	A human-readable description.
`retryable`	`true` if the same request may succeed later.
`request_id`	Include it when you contact support.
`details`	Extra structured context, when available.

Error codes#

Code	What to do
`UNAUTHORIZED`	The key is missing, invalid or expired. Sign in again.
`FORBIDDEN`	The key lacks a scope or a permission. Check scopes.
`NOT_FOUND`	Check the ID or slug.
`BUDGET_EXCEEDED`	Add credit, or raise the spending limit.
`CAPACITY_REACHED`	Wait and retry, or ask for less capacity.
`CONFLICT`	The resource changed state. Refresh it and retry.
`IDEMPOTENCY_PAYLOAD_CONFLICT`	A request ID was reused with different settings. Use a new ID, or the original settings.
`CONTRACT_INVALID`	The request failed validation. See `details`.
`PLATFORM_FAILURE`	GFT had an internal problem. Retry if `retryable` is `true`.
`CONNECTION_ERROR`	The CLI could not reach the API. Check `GFT_API_URL` and your network.

CLI exit codes#

Exit code	Meaning
`0`	Success.
`1`	Any other error, a declined confirmation, or a followed run that did not complete.
`2`	Not found, or invalid command-line arguments.
`3`	Authentication or permission error.
`4`	Budget exceeded.
`5`	Capacity reached.
`6`	Platform or connection error.

Use gft --json ... to get results as JSON in scripts. Errors stay on stderr as CODE: message request_id=....