Skip to main content

API Responses

Understanding VocaFuse API response formats, HTTP status codes, pagination, and filtering.

Response Format​

Success Response​

Successful responses return the requested data directly:

{
  "id": "606cf8f5-b294-4b9c-ad0e-3afeb99c6804",
  "tenant_id": "63f8fa32-0740-4263-9bed-578156b3526b",
  "status": "completed",
  "created_at": "2025-10-06T17:33:31",
  "updated_at": "2025-10-06T17:33:45",
  "uri": "/v1/voicenotes/606cf8f5-b294-4b9c-ad0e-3afeb99c6804"
}

For list endpoints, the response includes pagination metadata:

{
  "voicenotes": [...],
  "uri": "/v1/voicenotes?page=0&limit=10",
  "first_page_uri": "/v1/voicenotes?page=0&limit=10",
  "next_page_uri": "/v1/voicenotes?page=1&limit=10",
  "previous_page_uri": null,
  "page": 0,
  "page_size": 10,
  "total": 25
}

Error Response​

Error responses include a structured error object:

{
  "error": {
    "code": 2001,
    "message": "user_id is required in request body",
    "type": "ValidationError",
    "details": {
      "field": "user_id",
      "reason": "missing required field"
    }
  }
}

See the complete Error Reference for all error codes and handling strategies.

HTTP Status Codes​

VocaFuse uses standard HTTP status codes to indicate request success or failure:

Success Codes (2xx)​

StatusDescription
200 OKRequest succeeded, response body contains data
201 CreatedResource created successfully
204 No ContentRequest succeeded, no response body (typically for DELETE)

Client Error Codes (4xx)​

StatusDescription
400 Bad RequestInvalid parameters or malformed request
401 UnauthorizedInvalid or missing API credentials
403 ForbiddenValid credentials but insufficient permissions
404 Not FoundResource doesn't exist or not accessible
413 Payload Too LargeFile size exceeds maximum limit (25MB)
429 Too Many RequestsRate limit exceeded (see Rate Limits)

Server Error Codes (5xx)​

StatusDescription
500 Internal Server ErrorUnexpected server error
503 Service UnavailableService temporarily unavailable

Pagination​

All list endpoints (Voice Notes, API Keys, Webhooks) return paginated results to improve performance and manageability.

Query Parameters​

Control pagination using these query parameters:

ParameterTypeDefaultMaximumDescription
pageinteger0-Page number (0-indexed)
limitinteger50100Number of results per page

Example:

# Get page 2 with 25 results per page
curl "https://api.vocafuse.com/v1/voicenotes?page=1&limit=25" \
  -H "X-VocaFuse-API-Key: sk_live_..." \
  -H "X-VocaFuse-API-Secret: ..."

Response Metadata​

Every paginated response includes these metadata fields:

FieldTypeDescription
pageintegerCurrent page number (0-indexed)
page_sizeintegerNumber of results in this response
totalintegerTotal number of resources matching the query
uristringURI for the current page
first_page_uristringURI for the first page
next_page_uristringURI for next page (null if this is the last page)
previous_page_uristringURI for previous page (null if this is the first page)

Example Paginated Response​

{
  "voicenotes": [
    {
      "id": "3d219a45-af16-4e2f-b018-dd8e44b4cf12",
      "status": "transcribed",
      "created_at": "2025-10-06T17:33:31"
    }
  ],
  "uri": "/v1/voicenotes?page=1&limit=10",
  "first_page_uri": "/v1/voicenotes?page=0&limit=10",
  "next_page_uri": "/v1/voicenotes?page=2&limit=10",
  "previous_page_uri": "/v1/voicenotes?page=0&limit=10",
  "page": 1,
  "page_size": 10,
  "total": 25
}

Iterating Through Pages​

from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

# Method 1: Manual pagination
page = 0
while True:
    response = client.voicenotes.list(page=page, limit=50)
    
    for voicenote in response['voicenotes']:
        print(f"Voice note: {voicenote['id']}")
    
    # Check if there's a next page
    if response['next_page_uri'] is None:
        break
    
    page += 1

# Method 2: Iterate all results (SDK handles pagination)
for voicenote in client.voicenotes.list_all():
    print(f"Voice note: {voicenote['id']}")

Best Practices​

  • Use reasonable page sizes - Start with 50, adjust based on your needs
  • Don't skip pages - Process sequentially to avoid missing data
  • Check next_page_uri - Use it to detect the last page rather than calculating total pages
  • Handle empty results - The last page may have fewer than limit results
  • Cache when appropriate - For data that doesn't change frequently

Filtering​

Many list endpoints support filtering via query parameters to narrow down results.

Common Filter Parameters​

EndpointAvailable FiltersExample
Voice Notesstatus, date_from, date_to?status=transcribed&date_from=2025-10-01
API Keysstatus?status=active
Webhooksstatus?status=active

Date Filtering​

Use ISO 8601 date format (YYYY-MM-DD) for date filters:

from datetime import datetime, timedelta

# Get voice notes from last 7 days
seven_days_ago = (datetime.now() - timedelta(days=7)).strftime('%Y-%m-%d')
voicenotes = client.voicenotes.list(date_from=seven_days_ago)

# Get voice notes from specific date range
voicenotes = client.voicenotes.list(
    date_from='2025-10-01',
    date_to='2025-10-31'
)

Status Filtering​

Filter resources by their processing status:

# Get only completed voice notes
completed = client.voicenotes.list(status='transcribed')

# Get failed voice notes
failed = client.voicenotes.list(status='failed')

# Get processing voice notes
processing = client.voicenotes.list(status='processing')

Combining Filters​

Combine multiple filters to narrow results:

# Get completed voice notes from last 7 days
voicenotes = client.voicenotes.list(
    status='transcribed',
    date_from='2025-10-02',
    limit=100
)

# Get failed voice notes from October
voicenotes = client.voicenotes.list(
    status='failed',
    date_from='2025-10-01',
    date_to='2025-10-31'
)

Rate Limits​

API rate limits vary by plan to ensure service stability:

PlanRate LimitBurst Limit
Free10 req/min20 req/min
Pro100 req/min200 req/min
EnterpriseCustomCustom

Rate Limit Headers​

Every API response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642252800

Rate Limit Error​

When you exceed the rate limit, you'll receive a 429 status:

{
  "success": false,
  "error": {
    "code": 4003,
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "type": "RateLimitError",
    "details": {
      "retry_after": 60
    }
  }
}

Handling Rate Limits​

import time
from vocafuse import Client, RateLimitError

client = Client(api_key='sk_live_...', api_secret='...')

try:
    voicenotes = client.voicenotes.list()
except RateLimitError as e:
    # Wait for the specified retry_after duration
    wait_time = e.retry_after
    print(f'Rate limited. Waiting {wait_time} seconds...')
    time.sleep(wait_time)
    
    # Retry the request
    voicenotes = client.voicenotes.list()

Best Practices:

  • Implement exponential backoff for retries
  • Respect the retry_after value in error responses
  • Cache responses when appropriate
  • Use webhooks instead of polling for status updates
  • Monitor rate limit headers to avoid hitting limits

Next Steps​