Derapi uses standard HTTP response codes to signal success or failure. In cases of failure, Derapi's response includes a description of the failure in JSON format.

Error response JSON format

Requests which cannot be satisfied by the Derapi API will usually result in a non-2xx HTTP response code (except in the case of list endpoints supporting partial failures, as detailed below). In such cases, the response body will be a JSON object following the Problem Details for HTTP APIs RFC, having at least the following fields:

{
  "type": "https://docs.derapi.com/reference/errors#validation-error",
  "title": "Invalid request",
}

The values of these fields will be identical for errors of a particular type. When additional information about the specific error instance being reported, the detail key will also be present:

{
  "type": "https://docs.derapi.com/reference/errors#validation-error",
  "title": "Invalid request",
  "detail": "body: Additional properties are not allowed ('other' was unexpected)",
}

Specific error types

Bad Request

This error is returned when the request could not be processed by the server since it was not syntactically well-formed. Syntax errors may occur within the request body, path, or query string parameters.

The detail key will contain a summary of any syntax errors, and the errors key will contain a listing of each individual syntax error, with detail and pointer keys explaining the failure and providing a JSON Pointer to its source within the submitted document.

Example

{
   "detail": "invalid page token",
   "errors": [
     {
       "detail": "invalid page token",
       "in": "query"
     }
   ],
   "title": "Bad Request",
   "type": "https://docs.derapi.com/reference/errors#bad-request"
 }

Conflicting Events

A ConflictingEventsProblem is returned when a request cannot be processed due to conflicting control events. It contains a list of conflicting event IDs.

Remedy it by canceling the listed conflicting events, or adjusting the start and end times of the submitted event to avoid the conflicts.

Credentials Already Exist

A CredentialsAlreadyExistProblem is returned when the request cannot be processed because the provided credentials already exist in the system.

Incorrect Mode

An IncorrectModeProblem is returned when a request is made to an endpoint that requires a different API key mode than the one being used.

For example, using virtual mode credentials to access a production-only endpoint, or vice versa.

Correct the request by using the appropriate mode credentials.

Invalid Enrollment Application Time

An InvalidEnrollmentApplicationTimeProblem is returned when an Enrollment has an application that is later than the provided one.

Remedy it by ensuring the Enrollment application time is set correctly and does not exceed the provided time.

Invalid Enrollment Status

An InvalidEnrollmentStatusProblem is returned when an Enrollment has a conflicting status for the requested event.

It contains details about the conflicting status.

Remedy it by ensuring the Enrollment is in a valid state for the requested event.

Invalid Event Status

An InvalidEventStatusProblem is returned when a control event has an invalid status for the requested operation. It contains details about the conflicting status.

Remedy it by ensuring the control event is in a valid state for the requested operation.

Not Found

A NotFoundProblem is returned when a requested resource cannot be found.

It contains a URI reference that identifies the problem type, a human-readable summary, and a human-readable explanation specific to this occurrence of the problem.

Correct the request by ensuring the resource exists or by using the correct identifier.

Opt Out Conflict

An OptOutConflictProblem is returned when an opt-out has already been recorded for this Site with a different effective time.

The existing opt-out's effective time is included in the response.

Too Many Virtual Resources

A TooManyVirtualResourcesProblem is returned when a request exceeds the quota for virtual resources.

Remedy it by reducing the number of virtual resources in the request or by checking the quota limits.

See also https://docs.derapi.com/docs/virtual-mode#quotas.

Validation

This error is returned when the request submitted by the API caller did not conform to Derapi's API specification, or when it contained content which was otherwise semantically invalid. Validation failures may derive from problems within the request body, path, or query string parameters.

The detail key will contain a summary of any validation failures, and the errors key will contain a listing of each individual validation failure, with detail and pointer keys explaining the failure and providing a JSON Pointer to its source within the submitted document.

Example

{
   "detail": "body: Additional properties are not allowed ('other' was unexpected) (and 1 others)",
   "errors": [
     {
       "detail": "Additional properties are not allowed ('other' was unexpected)",
       "pointer": ""
     },
     {
       "detail": "-1 is less than the minimum of 0",
       "pointer": "/duration"
     }
   ],
   "title": "Validation Error",
   "type": "https://docs.derapi.com/reference/errors#validation"
 }