Errors - Verial

All errors return a structured JSON body with a machine-readable code and a human-readable message.

Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more request fields are invalid.",
    "details": {
      "name": ["Required field"]
    }
  }
}

Field	Type	Description
`error.code`	string	Machine-readable error code
`error.message`	string	Human-readable explanation
`error.details`	object	Field-level validation errors (when applicable)

Error Codes

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid request fields. Check `details` for specifics.
400	`BAD_REQUEST`	Malformed request body or invalid parameters.
401	`UNAUTHORIZED`	Missing or invalid API key.
404	`NOT_FOUND`	The requested resource does not exist or is not accessible.
409	`CONFLICT`	The request conflicts with the current state (e.g., starting a run on a deleted benchmark).
429	`RATE_LIMITED`	Too many requests. Wait and retry.
500	`INTERNAL_ERROR`	An unexpected error occurred on the server.

Handling Errors

Check the code field to determine how to respond programmatically:

try {
  const run = await verial.runs.create({ benchmarkId: 'invalid' })
} catch (err) {
  if (err.code === 'NOT_FOUND') {
    console.error('Benchmark not found')
  } else if (err.code === 'VALIDATION_ERROR') {
    console.error('Invalid request:', err.details)
  } else if (err.code === 'RATE_LIMITED') {
    // Wait and retry
    await sleep(parseInt(err.retryAfter ?? '60', 10) * 1000)
  } else {
    throw err
  }
}

Rate Limiting

The API enforces rate limits per API key. When you exceed the limit, you receive a 429 response with a Retry-After header indicating how many seconds to wait before retrying.

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Validation Errors

Validation errors include a details object that maps field names to arrays of error messages:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more request fields are invalid.",
    "details": {
      "name": ["String must contain at least 1 character(s)"],
      "timeout": ["Number must be greater than 0"]
    }
  }
}

​Error Format

​Error Codes

​Handling Errors

​Rate Limiting

​Validation Errors

Error Format

Error Codes

Handling Errors

Rate Limiting

Validation Errors