Error Handling Guide

Master error codes, debugging, and retry strategies

API Reference

Error Codes

Best Practices

Error Response Structure

All WAVE API errors follow a consistent format

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: title",
    "details": [
      {
        "field": "title",
        "issue": "required field missing",
        "expected": "string (1-200 characters)"
      }
    ],
    "request_id": "req_abc123xyz",
    "documentation_url": "https://docs.wave.inc/api-reference/errors#invalid_request"
  }
}

request_id is critical for debugging. Include it when contacting support.

Client Errors (4xx)

Errors caused by client request issues

400

Bad Request

Invalid request format or parameters

Example:

Missing required field "title" in stream creation

401

Unauthorized

Missing or invalid API key

Example:

API key expired or revoked

403

Forbidden

Insufficient permissions for this resource

Example:

API key lacks "streams:write" scope

404

Not Found

Resource does not exist

Example:

Stream ID "stream_xyz" not found

409

Conflict

Resource state conflict

Example:

Stream already active, cannot update while live

422

Unprocessable Entity

Validation error on request body

Example:

Invalid protocol value: must be webrtc, rtmp, or srt

429

Too Many Requests

Retryable

Rate limit exceeded

Example:

Exceeded 60 requests/minute on free tier

Server Errors (5xx)

Errors from WAVE infrastructure

500

Internal Server Error

Retryable

Unexpected server error

Example:

Database connection failed temporarily

502

Bad Gateway

Retryable

Upstream service unavailable

Example:

Cloudflare Calls temporarily unreachable

503

Service Unavailable

Retryable

Service temporarily down (maintenance or overload)

Example:

Scheduled maintenance in progress

504

Gateway Timeout

Retryable

Request timeout exceeded

Example:

Stream creation took >30 seconds

Retry Strategies

Production-grade retry patterns with exponential backoff

import { WaveClient } from '@wave/api-client';

import { DesignTokens, getContainer, getSection } from '@/lib/design-tokens';
const client = new WaveClient({
  apiKey: 'wave_live_xxxxx',
  retry: {
    maxAttempts: 3,
    initialDelay: 1000, // 1 second
    maxDelay: 30000, // 30 seconds
    exponentialBase: 2,
    retryableStatuses: [408, 429, 500, 502, 503, 504]
  }
});

// Automatic retry with exponential backoff
try {
  const stream = await client.streams.create({
    title: 'My Stream'
  });
} catch (error) {
  if (error.code === 'rate_limit_exceeded') {
    const retryAfter = error.headers['retry-after'];
    console.log(`Retry after ${retryAfter} seconds`);
  }
  throw error;
}

Official SDKs include automatic retry logic with exponential backoff and jitter out of the box.

Debugging Best Practices

1. Log Request IDs

Every error response includes a unique request_id. Log this for production debugging.

logger.error('API error', { request_id: error.request_id })

2. Validate Before Sending

Use TypeScript types or JSON Schema validation to catch errors before making API calls.

const validated = StreamSchema.parse(streamData)

3. Monitor Error Rates

Set up alerts for high error rates (above 5%) or specific error codes like 429 (rate limiting).

Sentry, Datadog, or CloudWatch for error tracking

4. Use Idempotency Keys

For POST/PATCH requests, include an Idempotency-Key header to safely retry.

Idempotency-Key: uuid-v4-generated-on-client