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

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

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

403 Permission Denied

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

404 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

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

503 Unavailable