WAVE uses structured error codes to help you quickly identify the root cause of failures. This page covers every error code you may encounter, organized by subsystem.

Error response format

All WAVE API errors conform to RFC 7807 (Problem Details for HTTP APIs). Every error response includes these fields:

Error code ranges

Authentication errors (WAVE-10xx)

These errors occur when the request cannot be authenticated or the authenticated user lacks the required permissions.

{% callout type=“warning” title=“Rotating API keys” %} If you suspect your API key has been compromised, revoke it immediately in the dashboard and generate a new one. All requests using the revoked key will return WAVE-1002. {% /callout %}

Stream errors (WAVE-20xx)

{% callout type=“info” title=“Stream key security” %} Stream keys are sensitive credentials. Never share them publicly or commit them to version control. If a stream key is compromised, reset it from the dashboard. {% /callout %}

Transcoding errors (WAVE-30xx)

These errors occur during the server-side transcoding of your ingest stream into adaptive bitrate renditions.

Playback errors (WAVE-40xx)

These errors are returned to viewers when playback cannot be started or maintained.

Billing errors (WAVE-50xx)

These errors are returned when a payment action fails or a plan limit is reached.

SRT-specific errors (WAVE-60xx)

These errors occur during SRT (Secure Reliable Transport) stream setup and operation.

WebRTC-specific errors (WAVE-70xx)

{% callout type=“info” title=“WebRTC firewall requirements” %} WebRTC requires UDP connectivity. If your network blocks UDP, WAVE will attempt a TURN relay fallback over TCP port 443. See the WebRTC Setup guide for full firewall requirements. {% /callout %}

Validation errors (WAVE-80xx)

Validation errors include a fields object in the response with per-field error details:

Rate limiting errors (WAVE-90xx)

{% callout type=“info” title=“Rate limit best practices” %} Check the X-RateLimit-Remaining header before making additional requests. Implement exponential backoff when you receive a 429 response. The Retry-After header tells you exactly how long to wait. {% /callout %}

Organization errors (WAVE-A0xx)

Email and broadcast errors (WAVE-B0xx)

Session errors (WAVE-C0xx)

These errors relate to user sessions, authentication state, and concurrent access.

Internal and infrastructure errors (WAVE-D0xx)

These errors indicate a server-side issue. In most cases, retrying after a short delay will succeed.

{% callout type=“warning” title=“Include the requestId when contacting support” %} Every error response includes a requestId. Always include this value when opening a support ticket — it allows the WAVE team to trace your exact request through the system. {% /callout %}

Internal error codes (programmatic reference)

The WAVE API also returns machine-readable code strings in the error response body. These map to the WAVE-numbered codes above and are useful for programmatic error handling in your application.

Handling errors in code

Use the code string for programmatic error handling and the WAVE-XXXX code for human-readable logging and support communication:

Retry strategies by error category

Not all errors should be retried. Use this table to determine whether to retry and how:

Getting help

{% callout type=“info” title=“Full API error reference” %} For programmatic error handling, see the API Reference which includes error response schemas and recommended retry strategies for each endpoint. {% /callout %}

Error Codes

WAVE uses structured error codes to help you quickly identify the root cause of failures. This page covers every error code you may encounter, organized by subsystem.

Error response format

All WAVE API errors conform to RFC 7807 (Problem Details for HTTP APIs). Every error response includes these fields:

type — A URL reference to the error documentation
title — A short human-readable summary
status — The HTTP status code
detail — A longer explanation with context-specific information
code — The WAVE error code (e.g. WAVE-1001)

{
  "type": "https://docs.wave.online/errors/WAVE-1001",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The provided API key is invalid or has been revoked.",
  "code": "WAVE-1001"
}

Some error responses also include:

requestId — A unique identifier for your request, useful when contacting support
recoverySteps — An array of suggested actions to resolve the error

{
  "type": "https://docs.wave.online/errors/WAVE-5001",
  "title": "Payment Failed",
  "status": 402,
  "detail": "The payment method on file was declined by the card issuer.",
  "code": "WAVE-5001",
  "requestId": "req_abc123def456",
  "recoverySteps": [
    "Verify your card details are correct",
    "Ensure sufficient funds are available",
    "Contact your bank to authorize the transaction",
    "Try a different payment method"
  ]
}

Error code ranges

Range	Category	HTTP Status	Description
WAVE-10xx	Authentication	401, 403	API keys, tokens, permissions
WAVE-20xx	Streams	400, 404	Stream lifecycle and configuration
WAVE-30xx	Transcoding	400, 500	Codec, resolution, and encoding issues
WAVE-40xx	Playback	403, 404	Viewer-side errors and regional routing
WAVE-50xx	Billing	402, 403	Payments, plans, and usage limits
WAVE-60xx	SRT	400, 503	SRT protocol handshake and configuration
WAVE-70xx	WebRTC	400, 503	ICE, TURN, and SDP negotiation
WAVE-80xx	Validation	400	Input validation and data format errors
WAVE-90xx	Rate Limiting	429	Request throttling and quota enforcement
WAVE-A0xx	Organization	403	Membership, suspension, and invite errors
WAVE-B0xx	Email	400, 429	Broadcast and email delivery errors
WAVE-C0xx	Session	401, 403	Session lifecycle and concurrent access
WAVE-D0xx	Internal	500, 502, 503	Server-side and infrastructure errors

Authentication errors (WAVE-10xx)

These errors occur when the request cannot be authenticated or the authenticated user lacks the required permissions.

Code	Title	HTTP	Cause	Resolution
WAVE-1001	Unauthorized	401	Missing or invalid authorization header	Include a valid API key in the `Authorization: Bearer <key>` header
WAVE-1002	Invalid API Key	401	The API key has been revoked or does not exist	Generate a new API key in Settings > API Keys
WAVE-1003	Expired Token	401	The JWT or session token has expired	Re-authenticate to obtain a fresh token
WAVE-1004	Insufficient Permissions	403	The API key lacks the required scope for this operation	Check the key’s permission scopes in the dashboard
WAVE-1005	Organization Mismatch	403	The API key belongs to a different organization	Use an API key from the correct organization

{% troubleshooter issue=“api-key-invalid” /%}

Stream errors (WAVE-20xx)

These errors relate to stream creation, connection, and lifecycle management.

Code	Title	HTTP	Cause	Resolution
WAVE-2001	Stream Not Found	404	The requested stream ID does not exist	Verify the stream ID in your WAVE dashboard
WAVE-2002	Stream Already Active	409	Another encoder is already connected to this stream	Disconnect the existing encoder or create a new stream
WAVE-2003	Ingest Rejected	400	The encoder’s codec or settings are not supported	Check that your encoder uses H.264/H.265 with AAC audio
WAVE-2004	Stream Limit Reached	403	Your plan’s concurrent stream limit has been reached	Upgrade your plan or stop an existing stream
WAVE-2005	Invalid Stream Key	401	The stream key does not match any active stream	Copy the stream key directly from the dashboard

Transcoding errors (WAVE-30xx)

These errors occur during the server-side transcoding of your ingest stream into adaptive bitrate renditions.

Code	Title	HTTP	Cause	Resolution
WAVE-3001	Transcode Failed	500	The ingest stream contains unsupported features	Switch to H.264 Main/High profile with AAC-LC audio
WAVE-3002	Resolution Unsupported	400	The input resolution exceeds your plan’s maximum	Reduce your encoder’s output resolution
WAVE-3003	Audio Format Invalid	400	The audio codec is not AAC	Configure your encoder to output AAC-LC at 48 kHz
WAVE-3004	Keyframe Interval Too High	400	Keyframe interval exceeds 4 seconds	Set your encoder’s keyframe interval to 2 seconds

Playback errors (WAVE-40xx)

These errors are returned to viewers when playback cannot be started or maintained.

Code	Title	HTTP	Cause	Resolution
WAVE-4001	Playback Unavailable	404	The stream is offline or has ended	Check the stream status in the dashboard
WAVE-4002	Region Unavailable	503	No edge server available in the viewer’s region	WAVE will automatically route to the nearest available region
WAVE-4003	Viewer Limit Reached	403	The concurrent viewer limit for your plan has been exceeded	Upgrade your plan for higher viewer capacity
WAVE-4004	DRM License Failed	403	The DRM license server could not validate the viewer	Clear browser cache and cookies, then retry

Billing errors (WAVE-50xx)

These errors are returned when a payment action fails or a plan limit is reached.

Code	Title	HTTP	Cause	Resolution
WAVE-5001	Payment Failed	402	The payment method on file was declined	Update your payment method in Billing Settings
WAVE-5002	Plan Expired	403	Your subscription has lapsed	Renew your plan to restore access
WAVE-5003	Usage Limit Exceeded	403	You have exceeded your plan’s monthly streaming hours	Upgrade to a higher plan or wait for the next billing cycle
WAVE-5004	Payment Method Expired	402	The card on file has passed its expiration date	Update the card expiration date or add a new payment method
WAVE-5005	Insufficient Funds	402	The card issuer reported insufficient funds	Add funds to your account or try a different payment method
WAVE-5006	Processing Error	500	A temporary issue occurred during payment processing	Wait a moment and retry; no charge has been made

SRT-specific errors (WAVE-60xx)

These errors occur during SRT (Secure Reliable Transport) stream setup and operation.

Code	Title	HTTP	Cause	Resolution
WAVE-6001	SRT Handshake Failed	503	The SRT handshake timed out or was rejected	Check the SRT Configuration guide
WAVE-6002	SRT Encryption Mismatch	400	The passphrase does not match	Ensure the encoder and WAVE passphrases match exactly
WAVE-6003	SRT Latency Too Low	400	The configured latency is too low for the network conditions	Increase the SRT latency buffer (recommended minimum: 120ms)

WebRTC-specific errors (WAVE-70xx)

These errors occur during WebRTC session establishment and media negotiation.

Code	Title	HTTP	Cause	Resolution
WAVE-7001	ICE Connection Failed	503	No viable network path was found	Check your firewall allows UDP on ports 10000-60000
WAVE-7002	TURN Fallback Failed	503	The TURN relay could not be established	Ensure port 443 (TCP) is not blocked by DPI
WAVE-7003	SDP Negotiation Failed	400	The browser and server could not agree on codecs	Update your browser to the latest version

Validation errors (WAVE-80xx)

These errors are returned when request data fails input validation.

Code	Title	HTTP	Cause	Resolution
WAVE-8001	Invalid Input	400	One or more request fields failed validation	Review the `detail` field for specific field-level errors
WAVE-8002	Missing Required Field	400	A required field was not included in the request	Include all required fields as specified in the API reference
WAVE-8003	Invalid Format	400	A field value does not match the expected format	Check data types, date formats (ISO 8601), and enum values
WAVE-8004	Payload Too Large	413	The request body exceeds the maximum allowed size	Reduce the payload size or use multipart upload for files

Validation errors include a fields object in the response with per-field error details:

{
  "type": "https://docs.wave.online/errors/WAVE-8001",
  "title": "Invalid Input",
  "status": 400,
  "detail": "The provided data is invalid. Please check your input and try again.",
  "code": "WAVE-8001",
  "fields": {
    "email": "Must be a valid email address",
    "title": "Must be between 1 and 200 characters"
  }
}

Rate limiting errors (WAVE-90xx)

These errors indicate your request was throttled to protect service quality.

Code	Title	HTTP	Cause	Resolution
WAVE-9001	Rate Limit Exceeded	429	Too many requests within the time window	Wait for the `Retry-After` header duration, then retry
WAVE-9002	Quota Exceeded	429	Your plan’s API call quota for this billing period is used up	Upgrade your plan or wait for the next billing cycle
WAVE-9003	Concurrent Limit	429	Too many simultaneous requests from your organization	Reduce parallelism or implement request queuing

Rate limit responses include headers to help you manage your request rate:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1707753600
Retry-After: 60

Organization errors (WAVE-A0xx)

These errors relate to organization membership, access, and management.

Code	Title	HTTP	Cause	Resolution
WAVE-A001	Organization Membership Required	403	You must be an organization member to access this resource	Ask your organization admin for an invite or create a new org
WAVE-A002	Organization Suspended	403	The organization has been suspended due to a policy violation	Check your email for violation notices and contact support
WAVE-A003	Organization Limit Reached	403	The organization has reached its resource limit for this tier	Remove unused resources or upgrade to a higher tier
WAVE-A004	Invitation Error	400	The organization invitation is expired, invalid, or already used	Ask the admin to resend the invitation

Email and broadcast errors (WAVE-B0xx)

These errors occur when sending email broadcasts or managing audience lists.

Code	Title	HTTP	Cause	Resolution
WAVE-B001	Email Send Failed	500	The email could not be delivered; content saved as draft	Verify your sender email is verified and audience list is valid
WAVE-B002	Template Error	400	Template variables are missing or the template syntax is invalid	Preview the email before sending; check all variable bindings
WAVE-B003	Audience Error	400	The selected audience contains no valid contacts	Verify the audience has contacts with valid email addresses
WAVE-B004	Email Quota Exceeded	429	Your email sending limit for this billing period is reached	Wait for quota reset or upgrade your plan

Session errors (WAVE-C0xx)

These errors relate to user sessions, authentication state, and concurrent access.

Code	Title	HTTP	Cause	Resolution
WAVE-C001	Session Expired	401	Your session expired due to inactivity	Sign in again; enable “Remember me” for longer sessions
WAVE-C002	Session Invalid	401	The session token could not be verified, possibly after a security update	Clear browser cookies and sign in again
WAVE-C003	Session Revoked	401	Your session was ended remotely (e.g. password change or admin action)	Sign in again with your current password
WAVE-C004	Too Many Active Sessions	403	You have exceeded the maximum number of concurrent sessions	Sign out from unused devices in security settings

Internal and infrastructure errors (WAVE-D0xx)

These errors indicate a server-side issue. In most cases, retrying after a short delay will succeed.

Code	Title	HTTP	Cause	Resolution
WAVE-D001	Internal Error	500	An unexpected server-side error occurred	Retry after a few seconds; contact support with the `requestId` if it persists
WAVE-D002	External Service Error	502	A downstream service (CDN, payment processor, etc.) failed	Retry after a few seconds; check status.wave.online for outages
WAVE-D003	Service Unavailable	503	The service is temporarily unavailable due to maintenance or load	Retry with exponential backoff; check the status page
WAVE-D004	Database Error	500	A temporary database connectivity or query issue	Retry after a few seconds; the issue is typically transient
WAVE-D005	Timeout	504	The request took too long to process	Retry with a smaller payload or simpler query

Internal error codes (programmatic reference)

The WAVE API also returns machine-readable code strings in the error response body. These map to the WAVE-numbered codes above and are useful for programmatic error handling in your application.

Code String	WAVE Code	HTTP	Description
`AUTH_ERROR`	WAVE-1001	401	Authentication required or failed
`AUTHENTICATION_ERROR`	WAVE-1002	401	Invalid credentials or API key
`PERMISSION_DENIED`	WAVE-1004	403	Insufficient permissions for the requested operation
`NOT_FOUND`	WAVE-2001	404	The requested resource does not exist
`VALIDATION_ERROR`	WAVE-8001	400	Input validation failed
`RATE_LIMIT_EXCEEDED`	WAVE-9001	429	Request rate limit exceeded
`NETWORK_ERROR`	WAVE-D003	503	Network connectivity issue
`DATABASE_ERROR`	WAVE-D004	500	Database operation failed
`SERVICE_ERROR`	WAVE-D001	500	General service-layer error
`EXTERNAL_API_ERROR`	WAVE-D002	502	Downstream service failure
`INTERNAL_ERROR`	WAVE-D001	500	Unclassified internal error

Handling errors in code

Use the code string for programmatic error handling and the WAVE-XXXX code for human-readable logging and support communication:

const response = await fetch('https://api.wave.online/v1/streams', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
 
if (!response.ok) {
  const error = await response.json();
 
  switch (error.code) {
    case 'WAVE-1001':
    case 'WAVE-1003':
      // Re-authenticate and retry
      await refreshToken();
      break;
    case 'WAVE-9001':
      // Respect rate limit
      const retryAfter = response.headers.get('Retry-After');
      await sleep(parseInt(retryAfter || '60', 10) * 1000);
      break;
    case 'WAVE-D001':
    case 'WAVE-D003':
      // Transient error, retry with backoff
      await retryWithBackoff(request);
      break;
    default:
      console.error(`WAVE error ${error.code}: ${error.detail}`);
  }
}

Retry strategies by error category

Not all errors should be retried. Use this table to determine whether to retry and how:

Category	Retryable	Strategy	Max Retries
Authentication	No	Re-authenticate, do not retry blindly	0
Validation	No	Fix the request payload	0
Stream	Depends	Retry only for transient errors	2
Billing	No	Update payment method, do not retry	0
Rate Limiting	Yes	Wait for `Retry-After`, then retry	3
Organization	No	Resolve the membership/access issue	0
Session	No	Re-authenticate	0
Transcoding	Depends	Fix encoder settings if config error	1
Playback	Yes	Retry with exponential backoff	3
Internal	Yes	Exponential backoff (1s, 2s, 4s)	3
External	Yes	Exponential backoff (2s, 5s, 15s)	3

Getting help

If you encounter an error that you cannot resolve using this guide:

Note the error code (e.g. WAVE-2001) and the requestId from the response
Check status.wave.online for ongoing incidents
Search the Help Center for related troubleshooting articles
Contact support at support@wave.online or call +1-888-WAVE-HLP with your error code and requestId

{% contact-support category=“technical” /%}

{% related-articles /%}