GearDex DocsPlatform API

Responses and errors

Keep the HTTP status, machine-readable code, and request context together so a failed call is easy to diagnose.

Studio APIv1Updated August 2026

GearDexStudio console

Request req_7F92A

Response inspector

Trace a failed request

api/studio-agent/v1

401invalid_token

403insufficient_scope

429rate_limited

200recovered

403 Forbiddenapplication/json

{
 "error": "Missing required scope:
 shoots:write",
 "code": "insufficient_scope"
}

Review the key, then retry once.

Response shape

Successful list requests return a data array plus pagination fields. Failed requests return an error message and a stable code that your integration can branch on. The message includes the detail an operator needs to act.

Error response

{
  "error": "Missing required scope: shoots:write",
  "code": "insufficient_scope"
}

Status codes

GearDex Studio API response status codes
Name	Type	Description
`200 / 201`	Success	The request completed. Create operations return the new record.
`400`	Bad request	A parameter or request body failed validation.
`401`	Unauthorized	The bearer token is missing, malformed, unknown, revoked, or expired.
`403`	Forbidden	The key lacks a required scope or the account cannot use the Studio API.
`404`	Not found	The requested record does not exist in the authenticated account.
`409`	Conflict	The write conflicts with the current record or a related resource.
`429`	Rate limited	The key exhausted its current one-minute request window.
`503`	Unavailable	GearDex could not safely check the rate limit or complete a dependent operation.
`500`	Server error	An unexpected server error prevented the request from completing.

Authentication codes

GearDex Studio API authentication error codes
Name	Type	Description
`missing_authorization`	401	The Authorization header was not sent.
`invalid_token`	401	The bearer value is malformed or is not a GearDex Studio key.
`key_not_found`	401	No active key matches the supplied token.
`key_revoked`	401	The key was revoked in GearDex settings.
`key_expired`	401	The key is past its configured expiration date.
`insufficient_scope`	403	The route requires a scope that the key does not have.
`feature_not_available`	403	Studio API access is not available for the account.
`rate_limited`	429	The key reached its request limit for the current window.
`rate_limit_unavailable`	503	GearDex could not verify the request window safely.
`studio_agent_config_error`	503	The server-side Studio API configuration is incomplete.

Validation errors

Query values and JSON bodies are checked before a route touches your workspace. List limits cannot exceed 100, offsets cannot be negative, and search text is capped at 100 characters. Write routes also check resource-specific fields and ownership.

Handle a failed request (JavaScript)

const response = await fetch(url, options)
const body = await response.json()

if (!response.ok) {
  throw new Error("GearDex request failed: " + (body.code ?? response.status))
}

return body

Retry safely

Retry read requests after short network failures and selected 5xx responses. For a 429, wait for the number of seconds inRetry-After, add a small random delay, and try again.