

Status and error handling¶

The success of requests MUST be indicated using HTTP status codes according to RFC 7231.

If the API responds with a status code between 100 and 399 the back-end indicates that the request has been handled successfully.

In general an error is communicated with a status code between 400 and 599. Client errors are defined as a client passing invalid data to the service and the service correctly rejecting that data. Examples include invalid credentials, incorrect parameters, unknown versions, or similar. These are generally "4xx" HTTP error codes and are the result of a client passing incorrect or invalid data. Client errors do not contribute to overall API availability.

Server errors are defined as the server failing to correctly return in response to a valid client request. These are generally "5xx" HTTP error codes. Server errors do contribute to the overall API availability. Calls that fail due to rate limiting or quota failures MUST NOT count as server errors.

JSON error object¶

A JSON error object SHOULD be sent with all responses that have a status code between 400 and 599.

{
  "id": "936DA01F-9ABD-4D9D-80C7-02AF85C822A8",
  "code": "SampleError",
  "message": "A sample error message.",
  "url": "http://www.openeo.org/docs/errors/SampleError"
}

Sending code and message is REQUIRED.

A back-end MAY add a free-form id (unique identifier) to the error response to be able to log and track errors with further non-disclosable details.
The code is either one of the standardized textual openEO error codes below or a proprietary error code.
The message explains the reason the server is rejecting the request. For "4xx" error codes the message explains how the client needs to modify the request.

By default the message MUST be sent in English language. Content Negotiation is used to localize the error messages: If an Accept-Language header is sent by the client and a translation is available, the message should be translated accordingly and the Content-Language header must be present in the response. See "How to localize your API" for more information.

url is an OPTIONAL attribute and contains a link to a resource that is explaining the error and potential solutions in-depth.

Standardized status codes¶

The openEO API usually uses the following HTTP status codes for successful requests:

200 OK: Indicates a successful request with a response body being sent.
201 Created Indicates a successful request that successfully created a new resource. Sends a Location header to the newly created resource without a response body.
202 Accepted Indicates a successful request that successfully queued the creation of a new resource, but it has not been created yet. The response is sent without a response body.
204 No Content: Indicates a successful request without a response body being sent.

The openEO API often uses the following HTTP status codes for failed requests:

400 Bad Request: The back-end responds with this error code whenever the error has its origin on client side and no other HTTP status code in the 400 range is suitable.
401 Unauthorized: The client did not provide any authentication details for a resource requiring authentication or the provided authentication details are not correct.
403 Forbidden: The client did provided correct authentication details, but the privileges/permissions of the provided credentials do not allow to request the resource.
404 Not Found: The resource specified by the path does not exist, i.e. one of the resources belonging to the specified identifiers are not available at the back-end. Note: Unsupported endpoints MUST use HTTP status code 501.
500 Internal Server Error: The error has its origin on server side and no other status code in the 500 range is suitable.
501 Not Implemented: An endpoint is specified in the openEO API, but is not supported.

If a HTTP status code in the 400 range is returned, the client SHOULD NOT repeat the request without modifications. For HTTP status code in the 500 range, the client MAY repeat the same request later.

All HTTP status codes defined in RFC 7231 in the 400 and 500 ranges can be used as openEO error code in addition to the most used status codes mentioned here. Responding with openEO error codes 400 and 500 SHOULD be avoided in favor of any more specific standardized or proprietary openEO error code.

openEO error codes¶

The following table of error codes is incomplete. These error codes will evolve over time. If you are missing any common error, please contribute it by adding an issue, creating a pull request or get in contact in our chat room.

The whole table of error codes is available as JSON file, which can be used by implementors to automatically generate error responses.

Account Management

openEO Error Code	Description	Message	HTTP Status Code
AuthenticationRequired	The client did not provide any authentication details for a resource requiring authentication or the provided authentication details are not correct.	Unauthorized.	401
AuthenticationSchemeInvalid	Invalid authentication scheme (e.g. Bearer).	Authentication method not supported.	403
CredentialsInvalid		Credentials are not correct.	403
TokenInvalid	Authorization token invalid or expired.	Session has expired.	403

EO Data Discovery

openEO Error Code	Description	Message	HTTP Status Code
CollectionNotFound	The requested collection does not exist.	Collection does not exist.	404

File Management

openEO Error Code	Description	Message	HTTP Status Code
ContentTypeInvalid	The specified media (MIME) type used in the Content-Type header is not allowed.	Media type specified in the request is not supported. Supported media types: {types}	400
FileContentInvalid	The content of the file is invalid.	File content is invalid.	400
FileLocked	The file is locked by a running job or another process.	File '{file}' is locked.	400
FileNotFound	The requested file does not exist.	File does not exist.	404
FileOperationUnsupported	The specified path is not a file and the operation is only supported for files. Path is likely a directory.	Operation is only supported for files.	400
FilePathInvalid	The specified path is invalid or not accessible. Path could contain invalid characters, an invalid user ID or point to an existing folder or a location outside of the user folder.	File path is invalid.	400
FileSizeExceeded	File exceeds allowed maximum file size.	File size it too large. Maximum file size: {size}	400
FileTypeInvalid	File format, file extension or media (MIME) type is not allowed.	File type not allowed. Allowed file types: {types}	400
StorageFailure	Server couldn't store file(s) due to server-side reasons.	Unable to store file(s).	500
StorageQuotaExceeded	The storage quota has been exceeded by the user.	Insufficient Storage.	400

General

openEO Error Code	Description	Message	HTTP Status Code
ContentTypeInvalid	The specified media (MIME) type used in the Content-Type header is not allowed.	Media type specified in the request is not supported. Supported media types: {types}	400
FeatureUnsupported	The back-end responds with this error whenever an endpoint is specified in the openEO API, but is not supported.	Feature not supported.	501
InfrastructureBusy	Service is generally available, but the infrastructure can't handle it at the moment as too many requests are processed.	Service is not available at the moment due to overloading. Please try again later.	503
InfrastructureMaintenance	Service is currently not available, but the infrastructure is currently undergoing maintenance work.	Service is not available at the moment due to maintenance work. Please try again later.	503
Internal	An internal server error with a proprietary message.	Server error: {message}	500
NotFound	To be used if the requested resource does not exist. Note: Unsupported endpoints MUST send an 'FeatureUnsupported' error. There are also specialized errors for missing jobs (JobNotFound), files (FileNotFound), etc.	Resource not found.	404
Timeout	The request took too long and timed out.	Request timed out.	408

Job Management

openEO Error Code	Description	Message	HTTP Status Code
BillingPlanInvalid	The specified billing plan is not on the list of available plans.	The specified billing plan is not valid.	400
BudgetInvalid	The specified budget is too low as it is either smaller than or equal to 0 or below the costs.	The specified budget is too low.	400
FormatArgumentInvalid		The value specified for the output format argument '{argument}' is invalid: {reason}	400
FormatArgumentUnsupported		Output format argument '{argument}' is not supported.	400
FormatUnsuitable		Data can't be transformed into the requested output format.	400
FormatUnsupported		Output format not supported.	400
JobLocked	The job is currently locked due to a running batch computation and can't be modified meanwhile.	Job is locked due to a queued or running batch computation.	400
JobNotFinished		Job has not finished computing the results yet. Please try again later.	400
JobNotFound	The requested job does not exist.	The job does not exist.	404
JobNotStarted	Job has not been queued or started yet or was canceled and not restarted by the user.	Job hasn't been started yet.	400
NoDataForUpdate	For PATCH requests: No valid data specified at all.	No valid data specified to be updated.	400
PaymentRequired	The budget required to fulfil the request are insufficient.	Payment required.	402
ProcessGraphMissing		No valid process graph specified.	400
PropertyNotEditable	For PATCH requests: The specified parameter can't be updated. It is read-only.	Specified property '{property}' is read-only.	400
StorageFailure	Server couldn't store file(s) due to server-side reasons.	Unable to store file(s).	500
StorageQuotaExceeded	The storage quota has been exceeded by the user.	Insufficient Storage.	400
Timeout	The request took too long and timed out.	Request timed out.	408
VariableDefaultValueTypeInvalid		The default value specified for the process graph variable '{variable_id}' is not of type '{type}'.	400
VariableIdInvalid		A specified variable ID is not valid.	400
VariableTypeInvalid		The data type specified for the process graph variable '{variable_id}' is invalid. Must be one of: string, boolean, number, array or object.	400
VariableValueMissing		No value specified for process graph variable '{variable_id}'.	400

Process Graph Management

openEO Error Code	Description	Message	HTTP Status Code
NoDataForUpdate	For PATCH requests: No valid data specified at all.	No valid data specified to be updated.	400
ProcessGraphMissing		No valid process graph specified.	400
ProcessGraphNotFound	The requested process graph does not exist.	Process graph does not exist.	404
PropertyNotEditable	For PATCH requests: The specified parameter can't be updated. It is read-only.	Specified property '{property}' is read-only.	400
VariableDefaultValueTypeInvalid		The default value specified for the process graph variable '{variable_id}' is not of type '{type}'.	400
VariableIdInvalid		A specified variable ID is not valid.	400
VariableTypeInvalid		The data type specified for the process graph variable '{variable_id}' is invalid. Must be one of: string, boolean, number, array or object.	400
VariableValueMissing		No value specified for process graph variable '{variable_id}'.	400

Processes

openEO Error Code	Description	Message	HTTP Status Code
CRSInvalid	Invalid or unsupported CRS specified.	CRS '{crs}' is invalid.	400
CollectionNotFound	The requested collection does not exist.	Collection does not exist.	404
CoordinateOutOfBounds		Coordinate is out of bounds.	400
FileContentInvalid	The content of the file is invalid.	File content is invalid.	400
FileNotFound	The requested file does not exist.	File does not exist.	404
JobNotFound	The requested job does not exist.	The job does not exist.	404
ProcessArgumentInvalid		The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}	400
ProcessArgumentRequired		Process '{process}' requires argument '{argument}'.	400
ProcessArgumentUnsupported		Process '{process}' does not support argument '{argument}'.	400
ProcessArgumentsMissing		Process '{process}' requires at least '{min_parameters}' parameters.	400
ProcessUnsupported		Process '{process}' is not supported.	400

Secondary Services Management

openEO Error Code	Description	Message	HTTP Status Code
BillingPlanInvalid	The specified billing plan is not on the list of available plans.	The specified billing plan is not valid.	400
BudgetInvalid	The specified budget is too low as it is either smaller than or equal to 0 or below the costs.	The specified budget is too low.	400
NoDataForUpdate	For PATCH requests: No valid data specified at all.	No valid data specified to be updated.	400
PaymentRequired	The budget required to fulfil the request are insufficient.	Payment required.	402
ProcessGraphMissing		No valid process graph specified.	400
PropertyNotEditable	For PATCH requests: The specified parameter can't be updated. It is read-only.	Specified property '{property}' is read-only.	400
ServiceArgumentInvalid		The value specified for the secondary service argument '{argument}' is invalid: {reason}	400
ServiceArgumentRequired		Required secondary service argument '{argument}' is missing.	400
ServiceArgumentUnsupported		Secondary service argument '{argument}' is not supported.	400
ServiceNotFound	The requested secondary service does not exist.	Service does not exist.	404
ServiceUnsupported		Secondary service type is not supported.	400
VariableValueMissing		No value specified for process graph variable '{variable_id}'.	400

Subscriptions

openEO Error Code	Description	Message	HTTP Status Code
WebSocketUpgradeNotRequested	In order to subscribe the connection must be upgradable to WebSockets.	Client sent invalid request to establish subscriptions.	400