Contents
All exceptions raised by API methods in DataONE include three basic elements of information and an optional element traceInformation as detailed in Types.ErrorMessage, repeated here for convenience.
Element | Cardinality | Description |
---|---|---|
errorCode | 1 | The error code. This is the HTTP error code (i.e. 4xx). In all cases, the HTTP Status Code value in the response headers should match this value. |
detailcode | 1 | A code that can be mapped to a specific location in the source code of the implementation. Implemented as a string with dot notation to indicate progressive levels of detail. |
pid | 0..1 | Required for exceptions that include an identifier in the constructor signature (e.g. NotFound, IdentifierNotUnique, SynchronizationFailed). |
nodeId | 0..1 | The node identifier of the machine that raised the exception |
description | 0..1 | A human readable message describing what happened |
traceInformation | 0..1 | Optional free text providing more information about the error condition. The intent of this element is to assist with debugging. Note that care should be taken to ensure senstive information is not accidentally exposed through error conditions. |
Expressed in xml-schema:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<!-- A derived string type with at least length 1 and it must contain non-whitespace -->
<xs:simpleType name="NonEmptyString">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:pattern value="[\s]*[\S][\s\S]*" />
</xs:restriction>
</xs:simpleType>
<!-- Exception type for error serialization in DataONE -->
<xs:complexType name="DataONEException">
<xs:sequence>
<xs:element name="description" minOccurs="0" maxOccurs="1" type="xs:string"></xs:element>
<xs:element name="traceInformation" minOccurs="0" maxOccurs="1" type="xs:anyType"></xs:element>
</xs:sequence>
<xs:attribute name="name" type="NonEmptyString" use="required"></xs:attribute>
<xs:attribute name="errorCode" type="xs:integer" use="required"></xs:attribute>
<xs:attribute name="detailCode" type="NonEmptyString" use="required"></xs:attribute>
<xs:attribute name='identifier' type="NonEmptyString" use="optional"></xs:attribute>
<xs:attribute name='nodeId' type="NonEmptyString" use="optional"></xs:attribute>
</xs:complexType>
</xs:schema>
HTTP error codes of relevance to the DataONE cicore are repeated here for convenience. Refer to the HTTP specification for a complete reference.
Code | Meaning | Description |
---|---|---|
400 | Bad Request | Bad request if the request REST operation is invalid, serialization is erroneous, mime type is not supported, or resource is not supported. |
401 | Unauthorized | Authentication failure. Credentials are required or were invalid. |
403 | Forbidden | The current user does not have the right to perform the requested action. |
404 | Not Found | The requested resource does not exist. |
405 | Method not allowed | The HTTP method used is not allowed on this resource. Response must include an Allow header indicating valid HTTP methods. |
406 | Not Acceptable | The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request. |
408 | Request Timeout | The client did not produce a request within the time that the server was prepared to wait. |
409 | Conflict | The request could not be completed due to a conflict with the current state of the resource. |
410 | Gone | The resource is known to be permanently deleted (as opposed to 404 which indicates uncertainty about the state of the object). |
413 | Request Entity Too Large | The server is refusing to process a request because the request entity is larger than the server is willing or able to process. |
415 | Unsupported Media Type | The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. |
500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
501 | Not Implemented | The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource. |
Exceptions can be serialized in different formats that vary according to where the error occurs and what caller the error message is being sent to. Four common serialization formats will be HTML, XML, JSON, and Log. The general approach for serializing error messages is indicated by way of example below. For errors raised in response to a HTTP call (e.g. through the REST interface), the error should be serialized in the format indicated in the request Accept header, defaulting to HTML.
Examples of a Exceptions.NotFound error raised by a request to MNRead.get() object 123XYZ from a Member Node. The trace information contains {'method':'mn.get'}.
In HTML:
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8" />
<title>Error: 404 Not Found (1020.1)</title>
</head>
<body>
<p>
<dl>
<dt>Error</dt>
<dd class='erroName'>NotFound</dd>
<dt>Code</dt>
<dd class='errorCode'>404</dd>
<dt>Detail Code</dt>
<dd class='detailCode'>1020.1</dd>
<dt>Identifier</dt>
<dd class='pid'>123XYZ</dd>
<dt>Node Identifier</dt>
<dd class='nodeId'>c3p0</dd>
</dl>
</p>
<p class='description'>The specified object does not exist on this node.</p>
<pre class='traceInformation'>
method: mn.get
hint: Please try resolving http://cn.dataone.org/cn/resolve/123XYZ
</pre>
</body>
</html>
In XML:
<error name='NotFound'
errorCode='404'
detailCode='1020.1'
pid='123XYZ'
nodeId='c3p0'>
<description>The specified object does not exist on this node.</description>
<traceInformation>
method: mn.get
hint: http://cn.dataone.org/cn/resolve/123XYZ
</traceInformation>
</error>
In JSON:
{
'name': 'NotFound',
'errorCode':404,
'detailCode': '1020.1',
'pid': '123XYZ',
'nodeId': 'c3p0',
'description': 'The specified object does not exist on this node.',
'traceInformation': 'method: mn.get
hint: http://cn.dataone.org/cn/resolve/123XYZ'
}
Log message body. This type of representation is presented here as a suggestion. The actual log representation may differ according to the actual implementation:
[detail:1020.1][pid:123XYZ, nodeId:c3p0, method:mn.get]The specified object does not exist on this node.
Exception | errorCode | Description |
---|---|---|
Exceptions.AuthenticationTimeout | 408 | The authentication request timed out. |
Exceptions.IdentifierNotUnique | 409 | The provided identifier conflicts with an existing identifier in the DataONE system. When serializing, the identifier in conflict should be rendered in traceInformation as the value of an identifier key. |
Exceptions.InsufficientResources | 413 | There are insufficient resources at the node to support the requested operation. |
Exceptions.InvalidCredentials | 401 | Indicates that the credentials supplied (to CN_crud.login() for example) are invalid for some reason. |
Exceptions.InvalidRequest | 400 | The parameters provided in the call were invalid. The names and values of parameters should included in traceInformation. |
Exceptions.InvalidSystemMetadata | 400 | The supplied system metadata is invalid. This could be because some required field is not set, the metadata document is malformed, or the value of some field is not valid. The content of traceInformation should contain additional information about the error encountered (e.g. name of the field with bad value, if the document is malformed). |
Exceptions.InvalidToken | 401 | The supplied authentication token (Session) could not be verified as being valid. |
Exceptions.NotAuthorized | 401 | The supplied identity information is not authorized for the requested operation. |
Exceptions.NotFound | 404 | Used to indicate that an object is not present on the node where the exception was raised. The error message should include a reference to the CN_crud.resolve() method URL for the object. |
Exceptions.NotImplemented | 501 | A method is not implemented, or alternatively, features of a particular method are not implemented. |
Exceptions.ServiceFailure | 500 | Some sort of system failure occurred that is preventing the requested operation from completing successfully. This error can be raised by any method in the DataONE API. |
Exceptions.UnsupportedMetadataType | 400 | The science metadata document submitted is not of a type that is recognized by the DataONE system. |
Exceptions.UnsupportedType | 400 | The information presented appears to be unsupported. This error might be encountered when attempting to register unrecognized science metadata for example. |
Exceptions.SynchronizationFailed | 0 | Sent to a Member Node from a Coordinating Node when an attempt to synchronize some object fails. |
Exceptions.VersionMismatch | 409 | The serialVersion of the system metadata being updated differs from the serialVersion supplied with the change request. |
The authentication request timed out.
Errorcode : | 408 |
---|---|
Parameters: |
|
The provided identifier conflicts with an existing identifier in the DataONE system. When serializing, the identifier in conflict should be rendered in traceInformation as the value of an identifier key.
Errorcode : | 409 |
---|---|
Parameters: |
|
There are insufficient resources at the node to support the requested operation.
Errorcode : | 413 |
---|---|
Parameters: |
|
Indicates that the credentials supplied (to CN_crud.login() for example) are invalid for some reason.
Errorcode : | 401 |
---|---|
Parameters: |
|
The parameters provided in the call were invalid. The names and values of parameters should included in traceInformation.
Errorcode : | 400 |
---|---|
Parameters: |
|
The supplied system metadata is invalid. This could be because some required field is not set, the metadata document is malformed, or the value of some field is not valid. The content of traceInformation should contain additional information about the error encountered (e.g. name of the field with bad value, if the document is malformed).
Errorcode : | 400 |
---|---|
Parameters: |
|
The supplied authentication token (Session) could not be verified as being valid.
Errorcode : | 401 |
---|---|
Parameters: |
|
The supplied identity information is not authorized for the requested operation.
Errorcode : | 401 |
---|---|
Parameters: |
|
Used to indicate that an object is not present on the node where the exception was raised. The error message should include a reference to the CN_crud.resolve() method URL for the object.
Errorcode : | 404 |
---|---|
Parameters: |
|
A method is not implemented, or alternatively, features of a particular method are not implemented.
Errorcode : | 501 |
---|---|
Parameters: |
|
Some sort of system failure occurred that is preventing the requested operation from completing successfully. This error can be raised by any method in the DataONE API.
Errorcode : | 500 |
---|---|
Parameters: |
|
The science metadata document submitted is not of a type that is recognized by the DataONE system.
Errorcode : | 400 |
---|---|
Parameters: |
|
The information presented appears to be unsupported. This error might be encountered when attempting to register unrecognized science metadata for example.
Errorcode : | 400 |
---|---|
Parameters: |
|
Sent to a Member Node from a Coordinating Node when an attempt to synchronize some object fails.
Errorcode : | 0 |
---|---|
Parameters: |
|
The serialVersion of the system metadata being updated differs from the serialVersion supplied with the change request.
Errorcode : | 409 |
---|---|
Parameters: |
|