# Responses and errors

Source: https://www.geardex.app/api-docs/errors

API access requires the GearDex Studio plan and a scoped Studio API key.

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

## 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**

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

Branch on the code

Messages may become clearer over time. Treat  `code`  as the programmatic value and show  `error`  to the operator.

## Status codes

**GearDex Studio API response status codes**

| Status | Meaning | When |
| --- | --- | --- |
| `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 or account used up its minute, or the account used up its day. |
| `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**

| Code | Status | Meaning |
| --- | --- | --- |
| `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 or account reached a request limit; the error says which. |
| `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)**

```js
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 in `Retry-After`, add a small random delay, and try again. The [rate limits](https://www.geardex.app/api-docs/rate-limits) page has a backoff example.

Be careful with writes

Do not replay a create, update, or delete request blindly. First check whether the original write completed, especially after a timeout where the client never received the response.