Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API. 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 message to figure out what has gone wrong.

Status codes

Here is a list of the different categories of status codes returned by the SaaS Custom Domains API. Use these to understand if a request was successful.

  • Name
    2xx
    Type
    Description

    A 2xx status code indicates a successful response.

  • Name
    4xx
    Type
    Description

    A 4xx status code indicates a client error — mostly happens when the API token is not valid or the request is malformed.

  • Name
    5xx
    Type
    Description

    A 5xx status code indicates a server error.

Error codes

Here is a list of the different error codes returned by the SaaS Custom Domains API. Use these to understand what has gone wrong.

These codes will be included in the JSON response body as error_code.

  • Name
    host_taken
    Type
    Description

    This means the host you are trying to use for upstream or a custom domain is already taken. Make sure you are using a unique host.

  • Name
    host_invalid
    Type
    Description

    This means the host you are trying to use for upstream or a custom domain is invalid. Make sure you are using a valid host.

  • Name
    host_blank
    Type
    Description

    This means the host you are trying to use for upstream or a custom domain is not provided. Make sure you are providing a host.

  • Name
    not_found
    Type
    Description

    This means the resource you are trying to access does not exist. Make sure you are using the correct resource UUID. The error message will also tell you what resource was not found.

Error types

Whenever a request is unsuccessful, the Saas Custom Domains API will return an error response with a message. You can use this information to understand better what has gone wrong and how to fix it.

Here is a list of the usual errors that happen when working with SaaS Custom Domains API.

  • Name
    401: Unauthorized
    Type
    Description

    This means the API token you are using is not valid. Make sure you are using the correct API token.

  • Name
    404: Not Found
    Type
    Description

    This means the resource you are trying to access does not exist. Make sure you are using the correct resource UUID. The error message will also tell you what resource was not found.

  • Name
    400: Bad Request
    Type
    Description

    This is unspecified client error that you shouldn't see often. It means the request you are trying to make is malformed. Make sure you are using the correct parameters and values.

  • Name
    5XX: Server Error
    Type
    Description

    If there's an issue with our servers, you will be served 5xx status codes. Please try again later or reach out to our support.

Example error response

{
  "error": "Upstream upstream_1234 (app.mysaas.com) not found.",
  "error_code": "upstream_not_found"
}