Errors

When you receive an error from the Terminus API, a response code will be set describing the error, and a payload matching the following structure will be determined with additional details:

{
  "error": {
    "code": 401,
    "message": "Request had invalid credentials.",
    "status": "UNAUTHENTICATED",
  }
}

Depending on the type of error that occurs, you may receive a details array that contains additional details about the error. Example detail responses for each error code are listed below.

It is generally recommended to record the error that you receive along with the Request ID so that you have them to reference when contacting our Support Team. If you receive a 423 or 503 error, then you can retry your requests using an appropriate expotential backoff implementation. Note that for 503 errors you should not universally retry any POST requests because it's possible for your request to have been partially fulfilled.

Error Codes

400 Bad Request

HTTP Response Code Issue Description
400 Bad Request Returned when the parameters sent do not match the required parameters' format

Example response:

{
  "error": {
    "code": 400,
    "message": "Bad request",
    "status": "[INVALID_ARGUMENT|FAILED_PRECONDITION|OUT_OF_RANGE]",
    "details": [{
      "fieldViolations": [
        {
          "field": "theFieldName",
          "description": "The error that occurred."
        }
      ]
    }]
  }
}

401 Unauthenticated

HTTP Response Code Issue Description
401 Unauthenticated Returned when a request is made without a valid API key

Please see Authentication to understand how authentication works for the Terminus API.

403 Permission Denied

HTTP Response Code Issue Description
403 Permission Denied Returned when the given user does not have permissions on the requested resource

Please see Authentication to understand how permissions work for the Terminus API.

404 Not Found

HTTP Response Code Issue Description
404 Not Found Returned when the given resource is not found
{
  "error": {
    "code": 404,
    "message": "Not found",
    "status": "UNAUTHENTICATED",
    "details": [{
      "resourceType": "terminus.account.v1.Account",
      "resourceName": "12345",
      "owner": "Terminus",
      "description": "The error that occurred"
    }]
  }
}

429 Resource Exhausted

HTTP Response Code Issue Description
429 Resource exhausted Returned when the given user has reached their API rate limits. Check the Retry-After header for how many seconds to wait before retrying, or the X-Retry-In for a string representation of how long to wait.

Example response:

{
  "error": {
    "code": 429,
    "message": "Not found",
    "status": "RESOURCE_EXHAUSTED",
    "details": [{
      "subject": "<The particular limit that was hit>",
      "description": "Description of the limit hit"
    }]
  }
}

500 Internal Error

HTTP Response Code Issue Description
500 Internal error Returned when there is an unrecoverable error in the API. If you continue to receive this error, please contact support and include your terminus-request-id.

503 Unavailable

HTTP Response Code Issue Description
503 Unavailable Returned when the service is currently unavailable.