ListenHubOpenAPI
EN中文

Error Handling

Error code reference and troubleshooting guide.

All ListenHub API responses use HTTP 200 status codes. Success and failure are distinguished by the code field in the response body: code = 0 means success, code ≠ 0 means failure.

Error Code Reference

Error CodeDescriptionSuggested Action
0Request succeeded—
21007Invalid API keyCheck that the Authorization header format is Bearer $LISTENHUB_API_KEY and verify the key is copied correctly
25002Resource not foundVerify the episodeId is correct
25008Invalid episode stateOnly occurs in the script-first workflow. Wait for script generation to complete before submitting audio synthesis. See Podcast API reference
26004Insufficient creditsCall GET /v1/user/subscription to check balance, then purchase credits
29003Invalid parametersValidate request payload against the API reference
29998Rate limit exceededOver the 3 RPM limit — implement backoff retry
91001Input content too shortIncrease input content length
91002Content policy violationReview content for compliance
91003-91007Content generation errorsCheck the message field for details

For unlisted non-zero error codes, check the message field in the response for details, or contact support@marswave.ai.

Error Response Format

All error responses follow the same JSON structure:

{
  "code": 21007,
  "message": "Invalid API key",
  "data": null
}

Common Troubleshooting

API key issues (21007):

  1. Confirm the Authorization header format is Bearer $LISTENHUB_API_KEY (note the space after Bearer)
  2. Confirm the API key is fully copied with no extra whitespace
  3. Visit API Key settings to verify key status

Rate limiting (29998):

  1. Creation requests are limited to 3 per minute (3 RPM)
  2. Read-only requests are not subject to this limit
  3. Implement exponential backoff retry

Next Steps

On this page

Error Code ReferenceError Response FormatCommon TroubleshootingNext Steps