Errors

Standard error response shape and complete error code reference.

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

Shape

{
  "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
service_unavailable	Temporary outage; retry with backoff

Handling errors

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

Authentication

Auth-related errors.

Rate limits

The 429 response.

SDKs

Type-safe error handling.