> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withgiga.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error codes, formats, and how to handle them

# Errors

All non-2xx responses from the WithGiga API use a consistent error envelope.

## Error format

```json theme={null}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable explanation of what went wrong",
    "hint": "Optional suggestion for how to fix it",
    "requestId": "uuid-for-support"
  }
}
```

Include the `requestId` when contacting support — it lets us trace the exact request in our logs.

***

## Error codes

### 400 Bad Request

| Code                   | Description                                                                   |
| ---------------------- | ----------------------------------------------------------------------------- |
| `INVALID_REQUEST`      | The request body or query parameters are malformed or missing required fields |
| `INVALID_FIELD`        | A specific field value is invalid — check the `hint` for the field name       |
| `UNSUPPORTED_PLATFORM` | The requested `platform` or `template` does not exist                         |

### 401 Unauthorized

| Code              | Description                                          |
| ----------------- | ---------------------------------------------------- |
| `UNAUTHORIZED`    | No `Authorization` header, or the API key is missing |
| `INVALID_API_KEY` | The API key is malformed or has been revoked         |

### 402 Payment Required

| Code                   | Description                                                                                  |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| `INSUFFICIENT_CREDITS` | Your credit balance is too low to complete the request — top up at [billing](/billing/plans) |

### 403 Forbidden

| Code                  | Description                                                   |
| --------------------- | ------------------------------------------------------------- |
| `FORBIDDEN`           | Your API key does not have permission to access this resource |
| `PLAN_LIMIT_EXCEEDED` | The requested action requires a higher plan tier              |

### 404 Not Found

| Code                 | Description                                                                                         |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| `RESOURCE_NOT_FOUND` | The requested resource (deployment, audit, file, etc.) does not exist or belongs to another account |

### 429 Too Many Requests

| Code                         | Description                                              |
| ---------------------------- | -------------------------------------------------------- |
| `RATE_LIMITED`               | Exceeded 60 requests/minute — check `Retry-After` header |
| `CONCURRENCY_LIMIT_EXCEEDED` | You've reached your plan's concurrent agent limit        |

### 500 Internal Server Error

| Code             | Description                                                                         |
| ---------------- | ----------------------------------------------------------------------------------- |
| `INTERNAL_ERROR` | An unexpected server-side error — retry with backoff; contact support if persistent |
| `SANDBOX_FAILED` | The E2B sandbox failed to provision — the `requestId` can help diagnose             |

***

## Handling errors in code

```javascript theme={null}
const res = await fetch("https://api.withgiga.ai/api/deployments/start", {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify({ ... })
});

if (!res.ok) {
  const { error } = await res.json();
  console.error(`[${error.code}] ${error.message}`);
  // handle specific codes
  if (error.code === "INSUFFICIENT_CREDITS") {
    // prompt user to top up
  }
}
```

## Retry guidance

| Status        | Retry? | Notes                                          |
| ------------- | ------ | ---------------------------------------------- |
| `400`         | No     | Fix the request before retrying                |
| `401` / `403` | No     | Check your API key and permissions             |
| `402`         | No     | Add credits before retrying                    |
| `404`         | No     | Verify the resource ID                         |
| `429`         | Yes    | Wait for `Retry-After` seconds                 |
| `500`         | Yes    | Retry with exponential backoff (1s, 2s, 4s, …) |