Overview

Errors

The errors in the TextReveal API are normalized. They are described with a code and a formatted JSON message.

Status codes

HTTP response status codes indicate whether a specific HTTP request has been successfully completed. Responses can be grouped into five classes:

  • informational responses (1xx)
  • successful responses (2xx)
  • redirects (3xx)
  • client errors (4xx)
  • servers errors (5xx)

On our apis, we use the following status codes:

  • 200Ok

    The request is successful.

  • 202Accepted

    The request is correct and accepted but it cannot be handled due to another process that is not finished.
    For example, an HTTP 202 response is returned in the TextReveal API when a user requests the computation of a timeserie while the instance is still in progress.

  • 204No Content

    The request is correct and accepted but it returns no content.
    For example, HTTP 204 response is returned in the TextReveal API when a user requests the computation of a timeserie while an error occurred when running the instance.

  • 400Bad Request

    The request was incorrect, please make sure that passed arguments are matching format in method's documentation.

  • 401Unauthorized

    You attempt to authenticate with an invalid username or API key.

  • 403Forbidden

    Your request is not allowed.

  • 404Not Found

    You attempt to request a resource which doesn't exist.

  • 429Too Many Requests

    You attempted to run too many analysis at the same time. Retry after an analysis is finished.

  • 500Internal Server Error

    Something unexpected happened on our end. Please try again or contact support.

  • 504Gateway Timeout

    The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server it needed to access in order to complete the request.

Error format

Each API page contains their specific response format, for the generic errors we use the following format:

  • message*string

    Error message.

    Example: "The server returned an unexpected response"
  • code*integer

    Error code.

    Example: 500
  • reason*string (enum)

    Error reason.

    Values: "invalid", "timeout", "offline", "unknown", "not_found", "unauthorized", "forbidden", "internal"
  • errorsobject[]

    Possible error causes, like query params, headers or body.

Example of an error response
{
  "message": "The server returned an unexpected response",
  "code": 500,
  "reason": "invalid",
  "errors": [
    {
      "message": "string",
      "field": "size",
      "reason": "invalid_type"
    }
  ]
}