Skip to main content
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"]
    }
  }
}
FieldTypeDescription
error.codestringMachine-readable error code
error.messagestringHuman-readable explanation
error.detailsobjectField-level validation errors (when applicable)

​
Error Codes

StatusCodeDescription
400VALIDATION_ERRORInvalid request fields. Check details for specifics.
400BAD_REQUESTMalformed request body or invalid parameters.
401UNAUTHORIZEDMissing or invalid API key.
404NOT_FOUNDThe requested resource does not exist or is not accessible.
409CONFLICTThe request conflicts with the current state (e.g., starting a run on a deleted benchmark).
429RATE_LIMITEDToo many requests. Wait and retry.
500INTERNAL_ERRORAn 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"]
    }
  }
}