Search API
  • Globus Search
  • Overview
  • API Usage & Basics
  • Ingest
  • Query
  • Types, Type Detection, and Schemas
  • Error Handling
  • API Reference
    • Batch Delete by Subject
    • Create or Update Entry
    • Delete by Query
    • Delete by Subject
    • Entry Delete
    • Entry Show
    • Index Create
    • Index Delete
    • Index List
    • Index Reopen
    • Index Show
    • Ingest
    • Query - GET
    • Query - POST
    • Role Create
    • Role Delete
    • Role List
    • Scroll Query
    • Subject Show
    • Task List
    • Task Show
  • Guides
    • Geospatial Search
    • Role Based Filtering
    • Searchable Files
  • Globus Search Limits
  • API Change History
Skip to main content
Globus Docs
  • APIs
    Auth Flows Groups Search Timers Transfer Globus Connect Server Compute Helper Pages
  • Applications
    Globus Connect Personal Globus Connect Server Premium Storage Connectors Compute Command Line Interface Python SDK JavaScript SDK
  • Guides
  • Support
    FAQs Mailing Lists Contact Us Check Support Tickets
  1. Home
  2. Globus Services
  3. Globus Search
  4. Error Handling

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.

  • Globus Search
  • Overview
  • API Usage & Basics
  • Ingest
  • Query
  • Types, Type Detection, and Schemas
  • Error Handling
  • API Reference
    • Batch Delete by Subject
    • Create or Update Entry
    • Delete by Query
    • Delete by Subject
    • Entry Delete
    • Entry Show
    • Index Create
    • Index Delete
    • Index List
    • Index Reopen
    • Index Show
    • Ingest
    • Query - GET
    • Query - POST
    • Role Create
    • Role Delete
    • Role List
    • Scroll Query
    • Subject Show
    • Task List
    • Task Show
  • Guides
    • Geospatial Search
    • Role Based Filtering
    • Searchable Files
  • Globus Search Limits
  • API Change History
© 2010- The University of Chicago Legal Privacy Accessibility