Skip to main content
All Vayu API errors return a JSON body with a consistent structure. Use type for broad SDK-level handling and code for specific programmatic logic.

​
Error response format

{
  "type": "invalid_request_error",
  "code": "resource_not_found",
  "message": "Customer with id cust_123 not found"
}
FieldTypeDescription
typestringError category — for broad handling
codestringSpecific machine-readable error code
messagestringHuman-readable explanation

​
Error types

typeMeaning
invalid_request_errorProblem with the request itself (bad input, not found, conflict)
authentication_errorMissing or invalid access token
rate_limit_errorToo many requests
api_errorUnexpected server-side error

​
Error codes

codeHTTP statustypeDescription
parameter_missing400invalid_request_errorA single required field is missing
parameter_invalid400invalid_request_errorA single field failed validation
validation_failed400invalid_request_errorMultiple fields failed validation
bad_request400invalid_request_errorMalformed JSON or other request-level error
authentication_failed401authentication_errorMissing or expired access token
resource_not_found404invalid_request_errorRequested resource does not exist
resource_already_exists409invalid_request_errorDuplicate — e.g. customer with this externalId already exists
request_too_large413invalid_request_errorPayload exceeds the 256 KB limit
rate_limit_exceeded429rate_limit_errorRate limit exceeded — see Rate Limits
internal_error500api_errorUnexpected server error — contact support if this persists

​
Validation errors

Validation errors come in two shapes depending on how many fields failed.

​
Single field

{
  "type": "invalid_request_error",
  "code": "parameter_missing",
  "message": "Missing required parameter: customerAlias",
  "param": "customerAlias"
}
code is parameter_missing if the field is absent, or parameter_invalid if it’s present but invalid.

​
Multiple fields

{
  "type": "invalid_request_error",
  "code": "validation_failed",
  "message": "2 validation errors in request",
  "errors": [
    {
      "param": "customFields[0].integrationEntityType",
      "message": "Invalid enum value. Expected 'Account' | 'Invoice' | ..."
    },
    {
      "param": "customFields[1].integrationEntityType",
      "message": "Invalid enum value. Expected 'Account' | 'Invoice' | ..."
    }
  ]
}
FieldTypeDescription
paramstringPresent on single-field errors — the parameter that failed
errorsarrayPresent on multi-field errors — each item has param and message

​
Handling errors in code

import { VayuClient } from 'vayu-ts';

const vayu = new VayuClient({ apiToken: process.env.VAYU_API_TOKEN });

try {
  const customer = await vayu.customers.create({ name: 'Acme Corp' });
} catch (error) {
  if (error.code === 'resource_already_exists') {
    console.log('Customer already exists');
  } else if (error.code === 'validation_failed') {
    error.errors.forEach(e => console.log(`${e.param}: ${e.message}`));
  } else if (error.code === 'parameter_missing' || error.code === 'parameter_invalid') {
    console.log(`${error.param}: ${error.message}`);
  } else {
    throw error;
  }
}