Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vobiz.ai/llms.txt

Use this file to discover all available pages before exploring further.

All errors follow a consistent format for easy parsing and debugging.

​
Error Response Format

All API errors use a standardized JSON format:
Standard Error Response
{
  "status": "error",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Account balance too low to complete this operation",
    "details": {
      "required": 1000,
      "available": 450,
      "currency": "USD"
    }
  },
  "timestamp": "2025-10-12T10:30:00.000Z",
  "requestId": "req_7a8b9c0d1e2f"
}

​
Response Fields

FieldDescription
statusAlways "error" for error responses
error.codeMachine-readable error code (uppercase, underscore-separated)
error.messageHuman-readable error description
error.detailsAdditional context (optional, varies by error)
timestampWhen the error occurred
requestIdUnique request identifier for support/debugging

​
HTTP Status Codes

​
2xx Success

CodeMeaning
200 OKRequest successful, response contains data
201 CreatedResource created successfully (e.g., trunk, sub-account)
204 No ContentRequest successful, no response body (e.g., DELETE operations)

​
4xx Client Errors

CodeMeaning
400 Bad RequestInvalid request format or parameters
401 UnauthorizedMissing or invalid authentication credentials
402 Payment RequiredInsufficient account balance
403 ForbiddenAuthenticated but lacking permission for this resource
404 Not FoundRequested resource does not exist
409 ConflictRequest conflicts with current state (e.g., duplicate username)
422 Unprocessable EntityValidation failed (see details for field errors)
429 Too Many RequestsRate limit exceeded

​
5xx Server Errors

CodeMeaning
500 Internal Server ErrorUnexpected server error (report via requestId)
502 Bad GatewayDownstream service unavailable
503 Service UnavailableService temporarily down or overloaded
504 Gateway TimeoutDownstream service timeout

​
Common Errors

​
Authentication Errors

Email/password combination incorrect.
{
  "status": "error",
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password"
  }
}
Access token has expired (use refresh token).
{
  "status": "error",
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Access token has expired. Use refresh token to obtain a new one."
  }
}
Account has been deactivated.
{
  "status": "error",
  "error": {
    "code": "ACCOUNT_INACTIVE",
    "message": "Account is inactive. Contact support to reactivate."
  }
}

​
Resource Errors

Trunk ID does not exist or belongs to a different account.
{
  "status": "error",
  "error": {
    "code": "TRUNK_NOT_FOUND",
    "message": "SIP trunk not found",
    "details": { "trunkId": "TRK_invalid123" }
  }
}
Trunk username already exists.
{
  "status": "error",
  "error": {
    "code": "DUPLICATE_USERNAME",
    "message": "Username already exists",
    "details": {
      "username": "mytrunk",
      "suggestion": "Try mytrunk2 or mytrunk_2025"
    }
  }
}

​
Balance & Billing Errors

Account balance too low.
{
  "status": "error",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance to purchase phone number",
    "details": {
      "required": 1000,
      "available": 450,
      "currency": "USD",
      "shortfall": 550
    }
  }
}
Payment processing failed.
{
  "status": "error",
  "error": {
    "code": "PAYMENT_FAILED",
    "message": "Payment declined by gateway",
    "details": {
      "gateway": "razorpay",
      "reason": "Insufficient funds in linked account"
    }
  }
}

​
Rate Limiting

Too many requests or calls.
{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "CPS limit exceeded for this trunk",
    "details": {
      "limitType": "cps",
      "limit": 10,
      "current": 15,
      "retryAfter": 1
    }
  }
}

​
Validation Errors

When request validation fails (422 status), the response includes detailed field-level errors:
Validation Error Response
{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "errors": [
        {
          "field": "password",
          "message": "Password must be at least 8 characters",
          "code": "MIN_LENGTH",
          "value": "abc"
        },
        {
          "field": "email",
          "message": "Invalid email format",
          "code": "INVALID_FORMAT",
          "value": "notanemail"
        },
        {
          "field": "maxCps",
          "message": "Must be between 1 and 1000",
          "code": "OUT_OF_RANGE",
          "value": 5000
        }
      ]
    }
  }
}
Handling validation errors: Parse the details.errors array to display field-specific error messages in your UI. Each error includes the field name, error code, and the invalid value.

​
Troubleshooting Guide

  • Check HTTP status code first - The status code category tells you who’s at fault: 4xx = client error (fix your request), 5xx = server error (retry or contact support).
  • Always log requestId - Save the requestId from error responses. When contacting support, include this ID for faster debugging and resolution.
  • Implement exponential backoff - For 429 (rate limit) and 503 (service unavailable) errors, retry with exponential backoff: wait 1s, then 2s, then 4s, etc. Check the Retry-After header if present.
  • Validate before sending - Implement client-side validation matching API requirements to catch errors before making requests. Reduces unnecessary API calls and improves user experience.
  • Monitor error rates - Track error response counts and types over time. Sudden spikes in specific error codes may indicate configuration issues or API changes requiring attention.
If you’re seeing unexpected errors across multiple requests, check the Vobiz Status Page for any active incidents before opening a support ticket.

​
Common 401 Fixes

  • Ensure X-Auth-ID and X-Auth-Token headers are included
  • Check token hasn’t expired
  • Verify account is active (is_active=true)