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:

  1. 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".

  2. 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".

  3. 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".

  4. 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".

  5. 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.

  6. 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.

Was this page helpful?