Exceptions Raised by MN and CN APIs

General

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 Exception Handling Codes

HTTP error codes of relevance to the DataONE services 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.

Serializing Exceptions

All error messages in DataONE are serialized in XML. In the future, DataONE interfaces may support additional serialization formats such as HTML and JSON, and the serialization format will be selected through normal HTTP content negotiation procedures (RFC2616).

An example of an XML serialized error message:

<error name='NotFound'
       errorCode='404'
       detailCode='1020.1'
       pid='123XYZ'
       nodeId='urn:node:DEMO1'>
  <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>

Note that the detailCode, pid, and nodeId attributes are optional. The description element is optional but strongly recommended, and traceInformation is optional though especially useful during development and testing.

The Exceptions

Summary of exceptions defined in the DataONE APIs

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.
exception Exceptions.AuthenticationTimeout(detailCode, description, traceInformation)

The authentication request timed out.

ErrorCode

408

Parameters

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.IdentifierNotUnique(detailCode, description, pid, traceInformation)

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

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • pid (Types.Identifier) – The identifier value that is in conflict.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.InsufficientResources(detailCode, description, traceInformation)

There are insufficient resources at the node to support the requested operation.

ErrorCode

413

Parameters

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.InvalidCredentials(detailCode, description, traceInformation)

Indicates that the credentials supplied (to CN_crud.login() for example) are invalid for some reason.

ErrorCode

401

Parameters

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.InvalidRequest(detailCode, description, traceInformation)

The parameters provided in the call were invalid. The names and values of parameters should included in traceInformation.

ErrorCode

400

Parameters

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.InvalidSystemMetadata(detailCode, description, traceInformation)

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

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.InvalidToken(detailCode, description, traceInformation)

The supplied authentication token (Session) could not be verified as being valid.

ErrorCode

401

Parameters

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.NotAuthorized(detailCode, description, traceInformation)

The supplied identity information is not authorized for the requested operation.

ErrorCode

401

Parameters

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.NotFound(detailCode, description, pid, traceInformation)

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

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • pid (Types.Identifier) – The identifier of the object that can not be located.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.NotImplemented(detailCode, description, traceInformation)

A method is not implemented, or alternatively, features of a particular method are not implemented.

ErrorCode

501

Parameters

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.ServiceFailure(detailCode, description, traceInformation)

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

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.UnsupportedMetadataType(detailCode, description, traceInformation)

The science metadata document submitted is not of a type that is recognized by the DataONE system.

ErrorCode

400

Parameters

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.UnsupportedType(detailCode, description, traceInformation)

The information presented appears to be unsupported.

This error might be encountered when attempting to register unrecognized science metadata for example.

ErrorCode

400

Parameters

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.SynchronizationFailed(detailCode, description, pid, traceInformation)

Sent to a Member Node from a Coordinating Node when an attempt to synchronize some object fails.

ErrorCode

0

Parameters

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • pid (Types.Identifier) – Identifier of the object that could not be synchronized.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

exception Exceptions.VersionMismatch(detailCode, description, pid, traceInformation)

The serialVersion of the system metadata being updated differs from the serialVersion supplied with the change request.

ErrorCode

409

Parameters

  • detailCode (string) – Set by the method raising the exception.

  • description (string) – Human readable description that can assist the caller in determining the cause of the exception.

  • pid (Types.Identifier) – Identifier of the system metadata for the object being updated.

  • traceInformation (dictionary) – Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must never be logged or recorded in error messages.

This material is based upon work supported by the National Science Foundation under Grant Numbers 083094 and 1430508.

Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.