Error Handling

Table of Contents

1. API Errors and Error Formatting
2. Task Failure and Errors

1. API Errors and Error Formatting

When the Globus Search API encounters an error while processing a request, it will return an HTTP 400-class or HTTP 500-class response with an error document.

Table 1. Typical Error Codes
400	Bad Request	Request was malformed e.g. A non-JSON document was sent to an API which requires JSON
401	Unauthorized	The call is not authenticated or authentication information was invalid. e.g. The caller used a token which has expired
403	Forbidden	The operation requires privileges which the caller does not have. e.g. Attempting to administer an index on which you do not have permissions
404	NotFound	Resource does not exist or is missing Or the caller is not permitted to see the resource
409	Conflict	The request is blocked, disallowed, or not consistent with the state of the service. e.g. Trying to cancel a task which has already completed
504	GatewayTimeout	The Globus Search backend was too slow trying to serve the request
500	Server Error	This should never happen! Contact `support@globus.org`

These errors will include a document body with a GError document

Table 2. GError Definition
Field Name	Type	Description
message	String	Descriptive error text. In some cases, this is acceptable to display directly to a user
code	String	A short universal identifier for the type of error, suitable for programmatic dispatch. More specific than `status`
request_id	String	A unique identifier for this request. Very useful for the Globus Team when troubleshooting.
status	Integer	This is a numeric response code indicating the class of error which occurred. When the `GError` document is sent via HTTP, this must be an integer >= 400, equivalent to the HTTP status code
error_data	Object or Array	Optional. An arbitrary JSON object or array, encoding detailed data about the error. For example, if multiple errors occurred, this may be an array of more GError documents. The format(s) of `error_data` will always be specified as part of an API call’s allowed error types if it contains specialized error data

{
  "code": "BadRequest.Generic",
  "message": "/v1/ingest requires a JSON payload",
  "status": 400
}

{
  "code": "BadRequest.Generic",
  "message": "/v1/ingest requires a JSON payload",
  "status": 400,
  "error_data": {
    "cause": "Either the data was not JSON formatted, or it is missing a Content-Type header of 'application/json'",
    "recommended_resolution": "Retry with Content-Type set, and check that the payload is valid JSON"
  }
}

{
  "code": "AccessForbidden.NeedsOwner",
  "message": "The operation you have requested requires \"Owner\" rights",
  "status": 403,
  "error_data": [
    {
      "code": "AccessForbidden.NeedsOwner",
      "message": "You are not permitted to FOO a BAR which you do not own"
    },
    {
      "code": "AccessForbidden.NeedsOwner.CouldNotClaim",
      "message": "This BAR already has an owner, you cannot claim ownership"
    }
  ]
}

Note

In this third example, the error_data array contains partial GError documents.

2. Task Failure and Errors

Tasks which fail in Globus Search will enter the FAILED state.

The underlying error which causes a task failure will be encoded either in the message or the additional_details field of the task document.

See the Get Task API for details on the fields in a task document.