## Suno Alexa Skill: Error Handling Guide for TTS Design

This document outlines the errors our Suno music skill can return to the Alexa platform. For each Alexa directive, it details:

1. **Nature of Error:** A description of what went wrong from a user or system perspective. This should inform the *intent* of the TTS.  
2. **Skill's Error Response (Type & Message):** The exact error `type` and `message` (and `subtypes` if applicable) the skill sends back to Alexa in the `ErrorResponse` payload. This is what Alexa's systems will see.  
3. **Alexa TTS:** A space for you to define the user-facing TTS for this scenario.

Our skill aims to provide specific error types where possible. `INTERNAL_ERROR` is used for unexpected issues or when a more specific Alexa error type isn't suitable. The `message` field in the error response often contains more specific details from our backend.

---

### 1\. Content Creation & Initial Playback

#### 1.1. Directive: `Alexa.Media.Search#GetPlayableContent` (with `action: GENERATE_CONTENT`)

*User asks Alexa to create a new song (e.g., "Alexa, ask Suno to make a song about...")*

| Nature of Error | Error Response | Alexa TTS |
| :---- | :---- | :---- |
| Requested song description was flagged by content filters (e.g., explicit language) | `Alexa.Media.ErrorResponse`  \`type: "CONTENT\_FILTERED"\` \`message: "Song Description flagged for moderation" \`subtypes: \["EXPLICIT\_LANGUAGE\_FILTER"\]\` (if applicable) |  |
| Requested song description was flagged by artist/copyright checks | `Alexa.Media.ErrorResponse`  \`type: "CONTENT\_FILTERED"\` \`message: "Song description contained artist name...") ***No subtype*** |  |
| User's Suno account doesn't have sufficient credits/subscription for generation. | `Alexa.Media.ErrorResponse`  \`type: "INSUFFICIENT\_USER\_SUBSCRIPTION"\` \`message: "INSUFFICIENT\_USER\_SUBSCRIPTION"\` |  |
| Skill authentication with Suno backend failed (e.g., invalid/expired token during generation). | `Alexa.ErrorResponse`  \`type: "INVALID\_AUTHORIZATION\_CREDENTIAL"\` \`message: "Invalid credentials for content generation."\` |  |
| Too many generation requests to Suno backend in a short period. | `Alexa.ErrorResponse`  \`type: "RATE\_LIMIT\_EXCEEDED"\` \`message: "Generation request rate limit exceeded."\` |  |
| Suno backend generation request failed because the prompt was unclear or too generic (e.g., "Please try rephrasing..."). | `Alexa.Media.ErrorResponse`  \`type: "USER\_CONTEXT\_MISMATCH"\` \`message: "Please try rephrasing with more specific details..."\` |  |
| General/unexpected error during content generation process (e.g., Suno API timeout, unexpected response, SSE issue for title/tags). | `Alexa.ErrorResponse`  \`type: "INTERNAL\_ERROR"\` \`message: "Content generation timed out."\` or \`"Failed to generate content: ..."\` or \`"An unexpected internal error occurred: ..."\` (or similar) |  |

#### 1.2. Directive: `Alexa.Media.Playback#Initiate`

*User selects a song to play (could be newly generated or existing), or Alexa auto-plays a generated song.*

| Nature of Error | Error Response | Alexa TTS |
| :---- | :---- | :---- |
| The specific song ID to play was not found or its details couldn't be fetched from Suno. | `Alexa.Media.ErrorResponse`  \`type: "CONTENT\_NOT\_FOUND"\` \`message: "No clip found with ID XXXXXX via Suno API"\`  |  |
| Song generation (audio/image) did not complete in time for playback, or an error occurred during generation. | `Alexa.ErrorResponse`  \`type: "INTERNAL\_ERROR"\` \`message: "MISSING\_AUDIO\_AND\_IMAGE"\` or \`"MISSING\_AUDIO"\` or \`"MISSING\_IMAGE"\` or \`"GENERATION\_NOT\_READY"\` (from \`wait\_for\_clip\_events\`) |  |
| Content being initiated was filtered during its generation process (e.g., post-lyrics moderation error). | `Alexa.Media.ErrorResponse`  \`type: "CONTENT\_FILTERED"\` \`message: "Content moderation failure..."\` (from \`wait\_for\_clip\_events\` via \`handle\_moderation\_error\`) \`subtypes: \["EXPLICIT\_LANGUAGE\_FILTER"\]\` (if applicable) |  |
| Skill authentication with Suno backend failed when fetching song details for playback. | `Alexa.ErrorResponse`  \`type: "INVALID\_AUTHORIZATION\_CREDENTIAL"\` \`message: "Invalid credentials for content retrieval."\` (if from \`get\_clip\_details\`) |  |
| General/unexpected error fetching song details or preparing for playback (e.g., Suno API timeout). | `Alexa.ErrorResponse`  \`type: "INTERNAL\_ERROR"\` \`message: "An unexpected internal error occurred..."\` (e.g. from \`get\_clip\_details\` timeout/request exception) |  |

---

### 2\. Content Retrieval & Library Browsing

#### 2.1. Directive: `Alexa.Media.Search#GetDisplayableContent` (GDC)

*User asks to see their library, browse genres, or search results are displayed (e.g., "Alexa, show my Suno library," "Alexa, search Suno for jazz songs").*

| Nature of Error | Error Response | Alexa TTS |
| :---- | :---- | :---- |
| No content found matching the user's request (e.g., empty library, no songs for a specific genre/search term). | `Alexa.Media.ErrorResponse`  \`type: "CONTENT\_NOT\_FOUND"\` \`message: "Could not find content matching the request."\` |  |
| Skill authentication with Suno backend failed when trying to access user's library or search. | `Alexa.ErrorResponse`  \`type: "INVALID\_AUTHORIZATION\_CREDENTIAL"\` \`message: "Invalid credentials for content search."\` (or similar for library fetch) |  |
| Too many requests to Suno backend when searching/browsing. | `Alexa.ErrorResponse`  \`type: "RATE\_LIMIT\_EXCEEDED"\` \`message: "Too many requests. Please try again later."\` |  |
| General/unexpected error during library fetch or search (e.g., Suno API timeout, unexpected response). | `Alexa.ErrorResponse`  \`type: "INTERNAL\_ERROR"\` \`message: "An unexpected internal error occurred..."\` |  |
| *(If GDC includes `action: GENERATE_CONTENT`)* | *(See errors under section 1.1)* |  |

#### 2.2. Directive: `Alexa.Media.Search#GetPlayableContent` (GPC) \- for existing content

*User asks to play a specific song by name/query, or Alexa attempts to play a search result (e.g., "Alexa, play my song 'Ocean Dreams' on Suno").*

| Nature of Error | Error Response | Alexa TTS |
| :---- | :---- | :---- |
| No song found matching the user's request (e.g., "play my song" but library is empty, or specific song title not found). | `Alexa.Media.ErrorResponse`  \`type: "CONTENT\_NOT\_FOUND"\` \`message: "Could not find content in your library."\` or \`"Could not find content matching the request."\` |  |
| Skill authentication with Suno backend failed when trying to find the song. | `Alexa.ErrorResponse`  \`type: "INVALID\_AUTHORIZATION\_CREDENTIAL"\` \`message: "Invalid credentials for content search."\` (or similar for clip details fetch) |  |
| Too many requests to Suno backend when trying to find the song. | `Alexa.ErrorResponse`  \`type: "RATE\_LIMIT\_EXCEEDED"\` \`message: "Too many requests. Please try again later."\` |  |
| General/unexpected error when trying to find the song (e.g., Suno API timeout). | `Alexa.ErrorResponse`  \`type: "INTERNAL\_ERROR"\` \`message: "An unexpected internal error occurred..."\` |  |

---

### 3\. Queue Navigation

#### 3.1. Directive: `Alexa.Audio.PlayQueue#GetNextItem` / `GetPreviousItem`

*User says "Alexa, next song" or "Alexa, previous song."*

**Note:** If there are no more items in the queue in the requested direction, the skill correctly returns `isQueueFinished: true` in the payload, which is not an error. Alexa typically handles this with TTS like "That's the end of the queue." The errors below are for *unexpected failures* when trying to fetch an item that *should* exist or be constructible.

| Nature of Error | Error Response | Alexa TTS |
| :---- | :---- | :---- |
| The next/previous song ID was identified, but its details couldn't be fetched from Suno (e.g. it was deleted, or API error). | `Alexa.Media.ErrorResponse`  \`type: "CONTENT\_NOT\_FOUND"\` \`message: "No clip found with ID XXXXXX via Suno API"\` (or similar if \`get\_clip\_details\` inside \`build\_play\_queue\_item\` fails) |  |
| Skill authentication with Suno backend failed when fetching next/previous song details. | `Alexa.ErrorResponse`  \`type: "INVALID\_AUTHORIZATION\_CREDENTIAL"\` \`message: "Invalid credentials for content retrieval."\` (or similar from \`get\_item\_in\_queue\` or \`get\_clip\_details\`) |  |
| Next/previous item was a generating track, and its audio/image did not complete in time or had an error. | `Alexa.ErrorResponse`  \`type: "INTERNAL\_ERROR"\` \`message: "MISSING\_AUDIO\_AND\_IMAGE"\` or similar (from \`wait\_for\_clip\_events\` if called for a non-complete GNI/GPI item) |  |
| General/unexpected error fetching or preparing the next/previous song (e.g., Suno API timeout). | `Alexa.ErrorResponse`  \`type: "INTERNAL\_ERROR"\` \`message: "An unexpected internal error occurred..."\` (e.g. from \`get\_item\_in\_queue\` or \`build\_play\_queue\_item\` failures) |  |

---

### 4\. Account Synchronization

#### 4.1. Directive: `Alexa.Audio#SyncUserContent`

*Alexa service periodically calls this to sync user's content library.* This is typically not directly invoked by a user voice command leading to immediate, but errors here can affect catalog accuracy.

| Nature of Error | Error Response | Alexa TTS |
| :---- | :---- | :---- |
| Skill failed to communicate with Suno backend to process the account sync request. | `Alexa.ErrorResponse`  \`type: "INTERNAL\_ERROR"\` \`message: "Failed to process account sync request"\` | *N/A* |

#### 4.2. Event: `AlexaSkillEvent.SkillAccountLinked`

*Alexa service sends this event when a user links their account.* This is not a user-facing directive with TTS. The skill returns an HTTP status.

| Nature of Error | Skill's Response (HTTP Status & Body) | Alexa TTS |
| :---- | :---- | :---- |
| Skill failed to notify Suno backend about the account linking. | `Alexa.ErrorResponse`  \`type: "INTERNAL\_ERROR"\` \`message: "Failed to process account linking request"\` | *N/A* |

---

### 5\. General / Cross-Cutting Errors

These errors can be returned for various directives if fundamental issues occur.

| Nature of Error | Error Response | Alexa TTS |
| :---- | :---- | :---- |
| The request sent by Alexa to the skill was malformed or unrecognized by the skill's basic router. | `Alexa.ErrorResponse`  \`type: "INVALID\_DIRECTIVE"\` \`message: "Request body is not valid JSON..."\` or \`"Unrecognized request format..."\` or \`"Unsupported directive or version..."\` |  |
| A completely unexpected error occurred within the skill, or the skill took too long to respond (Lambda timeout). | `Alexa.ErrorResponse`  \`type: "INTERNAL\_ERROR"\` \`message: "An unexpected internal error occurred: ..."\` or \`"Handler failed to generate a response..."\` (Actual message may vary) |  |
| The user's account with Suno has a problem (not explicitly used but handled by `AccountProblemError` if it were raised). | `Alexa.ErrorResponse`  \`type: "ACCOUNT\_PROBLEM"\` \`message: (message from AccountProblemError)\` |  |

---

**Note on Timeouts:**

* Our skill makes external calls to the Suno backend, which have their own timeouts (typically 3-5 seconds). If these are exceeded, they usually result in an `Alexa.ErrorResponse` with `type: "INTERNAL_ERROR"`.  
* The AWS Lambda function itself has an overall timeout. If this is exceeded, Alexa will receive a generic error, often interpreted as an `INTERNAL_ERROR`. The skill includes an artificial delay for content generation, which consumes from this budget.