> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Standard error response shape and complete error code reference.

vly's API returns errors in a consistent JSON shape across every endpoint.

## Shape

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "The 'prompt' field is required.",
    "param": "prompt"
  }
}
```

| Field | Type | Description |
| - | - | - |
| `code` | string | Machine-readable error code (snake\_case) |
| `message` | string | Human-readable message |
| `param` | string | (optional) Field name that caused the error |

## HTTP status codes

| Code | Meaning |
| - | - |
| 200 | Success |
| 201 | Created |
| 202 | Accepted (async operation queued) |
| 204 | No content |
| 400 | Bad request — validation failed |
| 401 | Unauthorized — missing or invalid API key |
| 403 | Forbidden — auth valid but lacks scope |
| 404 | Not found |
| 409 | Conflict — resource already exists |
| 422 | Unprocessable entity — semantic error |
| 429 | Too many requests — rate limited |
| 500 | Internal server error — vly-side bug |
| 503 | Service unavailable — temporary outage |

## Error code reference

### Authentication

| Code | Meaning |
| - | - |
| `missing_api_key` | No `Authorization` header |
| `invalid_api_key` | Key not recognized or revoked |
| `expired_api_key` | Key passed expiration |
| `insufficient_scope` | Key valid but missing required scope |

### Validation

| Code | Meaning |
| - | - |
| `invalid_request` | Generic validation error (see `param`) |
| `missing_field` | Required field absent |
| `invalid_field_type` | Field has wrong type |
| `invalid_field_value` | Field value out of range / wrong format |

### Resource

| Code | Meaning |
| - | - |
| `not_found` | Resource doesn't exist or you can't access it |
| `already_exists` | Tried to create a resource with a duplicate unique field |
| `dependency_missing` | Referenced resource doesn't exist |

### Rate / quota

| Code | Meaning |
| - | - |
| `key_rate_limited` | Too many requests |
| `quota_exceeded` | Plan-level cap hit (e.g., monthly credits) |

### Server

| Code | Meaning |
| - | - |
| `internal_error` | Bug on vly's side; report via [support](mailto:support@vly.ai) |
| `service_unavailable` | Temporary outage; retry with backoff |

## Handling errors

```typescript theme={null}
try {
  const project = await vly.projects.create({ /* ... */ });
} catch (err) {
  if (err.code === "key_rate_limited") {
    // wait and retry
  } else if (err.code === "insufficient_scope") {
    // generate a new key with the right scope
  } else {
    throw err;
  }
}
```

The SDKs surface the same `code` and `message` properties on thrown errors.

## Related

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Auth-related errors.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/api-reference/rate-limits">
    The 429 response.
  </Card>

  <Card title="SDKs" icon="code" href="/api-reference/sdks/typescript">
    Type-safe error handling.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.