Errors
In this guide, we will talk about what happens when something goes wrong while you work with the Lettercast API. Mistakes happen, and mostly they will be yours, not ours. Let's look at some status codes and error types you might encounter.
You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support).
Before reaching out to support with an error, please be aware that 99% of all reported errors are, in fact, user errors. Therefore, please carefully check your code before contacting Lettercast support.
Status codes
Here is a list of the different categories of status codes returned by the Lettercast API. Use these to understand if a request was successful.
- Name
2xx
- Description
A 2xx status code indicates a successful response.
- Name
4xx
- Description
A 4xx status code indicates a client error — this means it's a you problem.
- Name
5xx
- Description
A 5xx status code indicates a server error — you won't be seeing these.
Error types
Whenever a request is unsuccessful, the Lettercast API will return an error response with an error type and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.
Here is a list of the error types supported by the Lettercast API — use these to understand what you have done wrong.
- Name
api_error
- Description
This means that we made an error, which is highly speculative and unlikely.
- Name
invalid_request
- Description
This means that you made an error, which is much more likely.
- Name
unauthorized
- Description
This means that you're not authenticated or don't have permission to access the requested resource.
- Name
not_found
- Description
This means that the requested resource (e.g., a pod or file) couldn't be found.
- Name
forbidden
- Description
This means that you don't have the necessary permissions to access the requested resource.
Error response
{
"type": "invalid_request",
"message": "File is empty",
"documentation_url": "https://lettercast.ai/docs/errors/invalid_request"
}
Authentication errors
When working with the Lettercast API, you might encounter authentication-related errors. Remember that Lettercast offers one way of authentication: OAuth2 with a token.
If you receive a 401 Unauthorized
status code, it usually means there's an issue with your OAuth2 token.
Make sure you're including the token correctly in the Authorization
header of your requests:
Authorization: Bearer API_KEY
If you're still having issues, verify that your OAuth2 token is valid and hasn't expired. You can generate a new token in the Lettercast dashboard under API settings if needed.
Common error scenarios
Here are some common error scenarios you might encounter when using the Lettercast API:
-
Empty file upload: If you try to upload an empty file, you'll receive a 400 Bad Request error with the message "File is empty".
-
Invalid token: If your authentication token is invalid or missing, you'll receive a 401 Unauthorized error with the message "Token not found in request".
-
Pod not found: When trying to access a pod that doesn't exist, you'll receive a 404 Not Found error with the message "Pod not found".
-
Accessing another user's pod: If you try to access a pod that belongs to another user, you'll receive a 403 Forbidden error with the message "Access denied".
-
Pod audio or video not found: When trying to access audio or video for a pod that doesn't have these files, you'll receive a 404 Not Found error with a message indicating that the audio or video wasn't found for the specified pod ID.
-
Internal server error: If there's an unexpected error on the server side, you'll receive a 500 Internal Server Error. In this case, please try your request again or contact support if the issue persists.
Remember to handle these errors gracefully in your application and provide appropriate feedback to your users.