> ## Documentation Index
> Fetch the complete documentation index at: https://guide.withvayu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> HTTP error codes and error response format

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

```json theme={null}
{
  "type": "invalid_request_error",
  "code": "resource_not_found",
  "message": "Customer with id cust_123 not found"
}
```

| Field     | Type   | Description                          |
| --------- | ------ | ------------------------------------ |
| `type`    | string | Error category — for broad handling  |
| `code`    | string | Specific machine-readable error code |
| `message` | string | Human-readable explanation           |

## Error types

| `type`                  | Meaning                                                          |
| ----------------------- | ---------------------------------------------------------------- |
| `invalid_request_error` | Problem with the request itself (bad input, not found, conflict) |
| `authentication_error`  | Missing or invalid access token                                  |
| `rate_limit_error`      | Too many requests                                                |
| `api_error`             | Unexpected server-side error                                     |

## Error codes

| `code`                    | HTTP status | `type`                  | Description                                                               |
| ------------------------- | ----------- | ----------------------- | ------------------------------------------------------------------------- |
| `parameter_missing`       | 400         | `invalid_request_error` | A single required field is missing                                        |
| `parameter_invalid`       | 400         | `invalid_request_error` | A single field failed validation                                          |
| `validation_failed`       | 400         | `invalid_request_error` | Multiple fields failed validation                                         |
| `bad_request`             | 400         | `invalid_request_error` | Malformed JSON or other request-level error                               |
| `authentication_failed`   | 401         | `authentication_error`  | Missing or expired access token                                           |
| `resource_not_found`      | 404         | `invalid_request_error` | Requested resource does not exist                                         |
| `resource_already_exists` | 409         | `invalid_request_error` | Duplicate — e.g. customer with this `externalId` already exists           |
| `request_too_large`       | 413         | `invalid_request_error` | Payload exceeds the 256 KB limit                                          |
| `rate_limit_exceeded`     | 429         | `rate_limit_error`      | Rate limit exceeded — see [Rate Limits](/api-reference/pages/rate-limits) |
| `internal_error`          | 500         | `api_error`             | Unexpected server error — contact support if this persists                |

## Validation errors

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

### Single field

```json theme={null}
{
  "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

```json theme={null}
{
  "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' | ..."
    }
  ]
}
```

| Field    | Type   | Description                                                         |
| -------- | ------ | ------------------------------------------------------------------- |
| `param`  | string | Present on single-field errors — the parameter that failed          |
| `errors` | array  | Present on multi-field errors — each item has `param` and `message` |

## Handling errors in code

<CodeGroup>
  ```typescript TypeScript theme={null}
  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;
    }
  }
  ```

  ```python Python theme={null}
  from vayu_client import VayuClient
  from vayu_client.exceptions import VayuAPIError

  vayu = VayuClient(api_token=os.environ["VAYU_API_TOKEN"])

  try:
      customer = vayu.customers.create(name="Acme Corp")
  except VayuAPIError as e:
      if e.code == "resource_already_exists":
          print("Customer already exists")
      elif e.code == "validation_failed":
          for err in e.errors:
              print(f"{err['param']}: {err['message']}")
      elif e.code in ("parameter_missing", "parameter_invalid"):
          print(f"{e.param}: {e.message}")
      else:
          raise
  ```

  ```go Go theme={null}
  import (
      VayuSDK "github.com/weft-finance/vayu-go"
      "os"
      "fmt"
  )

  vayu := VayuSDK.NewVayu(os.Getenv("VAYU_API_TOKEN"))

  _, err := vayu.Customers.CreateCustomer(VayuSDK.CreateCustomerRequest{Name: "Acme Corp"})
  if err != nil {
      if vayuErr, ok := err.(*VayuSDK.VayuError); ok {
          fmt.Println("API error:", vayuErr.Body)
      }
      panic(err)
  }
  ```
</CodeGroup>