Errors | Developer Guides | Docbyte Knowledge Base

When a /v2 call fails, you get an HTTP error status and a JSON body with the same fields every time. Your code can act on two of them: code tells you the kind of error, and reason tells you exactly what went wrong. The message is only there to help you while you develop.

What an error looks like

This call asks for more SIPs per page than the endpoint allows:

GET /v2/sip?pageSize=5000

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Error-Id: 3f6c2a9e-8b41-4d7a-9c55-2e1f0b7d4a10

JSON

{
  "code": "VALIDATION_ERROR",
  "reason": "OUT_OF_RANGE",
  "message": "pageSize must be between 1 and 1000",
  "errorId": "3f6c2a9e-8b41-4d7a-9c55-2e1f0b7d4a10",
  "params": { "field": "pageSize", "min": 1, "max": 1000 },
  "details": [
    {
      "field": "pageSize",
      "reason": "OUT_OF_RANGE",
      "message": "pageSize must be between 1 and 1000",
      "params": { "field": "pageSize", "min": 1, "max": 1000 }
    }
  ]
}

The error body

Field	Type	Description
`code`	string	The kind of error, which matches the HTTP status. See Error codes.
`reason`	string	What went wrong, exactly. See Reasons.
`message`	string	A description in English, for developers. It's never empty.
`errorId`	string (UUID)	The ID of this error.
`params`	object	The values that go with the reason, such as a field name or a limit. Only there when the reason has values.
`details`	array	One entry per field with a problem, each with its own `field`, `reason`, `message`, and `params`. Only there when the error is about specific fields.

What your code can rely on

Switch on reason to handle a specific error, or to show your own text to your users. Fill in your text with the values in params.
Fall back to code for a reason that your code doesn't know.
Use details to mark the fields with a problem, for example in a form. When several fields fail at once, details lists each field, and the top-level reason is INVALID_REQUEST, except for MUTUALLY_EXCLUSIVE_FIELDS, which keeps its own.
Don't parse message. Its text can change, and for a server error it's only a general description.

When you ask Docbyte about a failed call, send the errorId. The same ID is in the archive's logs.

Error codes

`code`	HTTP status	What it means
`VALIDATION_ERROR`	`400`	Something in your request isn't valid.
`PAYLOAD_TOO_LARGE`	`413`	Your request body, or a value in it, is too large.
`NOT_AUTHORIZED`	`401`	The archive couldn't authenticate you.
`NO_PERMISSION`	`403`	You're authenticated, but you can't do this.
`NOT_FOUND`	`404`	What you asked for doesn't exist, or you can't see it.
`CONFLICT`	`409`	The action conflicts with the current state of the resource.
`GONE`	`410`	What you asked for isn't available anymore.
`RANGE_NOT_SATISFIABLE`	`416`	The `Range` header of a download asks for bytes outside the file.
`SERVICE_UNAVAILABLE`	`503`	A service that the call needs isn't available.
`EXCEPTION`	`500`	Something went wrong on the server.

A few errors keep an HTTP status that isn't the default for their code. For example, a request with an unsupported Content-Type gets a 415 status with the code VALIDATION_ERROR. Use the HTTP status to see that a call failed, and use code and reason to decide what to do.

Reasons

Validation errors (400)

`reason`	What it means for you
`INVALID_REQUEST`	The request isn't valid. Check `message` and `details`. You also get it when several fields fail at once.
`REQUIRED_FIELD`	A required field is missing. `params.field` names it.
`INVALID_VALUE`	A field has a value that isn't allowed. `params.field` names it.
`OUT_OF_RANGE`	A number or a length is outside its limits. `params.min` and `params.max` hold the limits.
`INVALID_FORMAT`	A value doesn't have the expected format, for example an email address.
`INVALID_DATE`	A date isn't a valid ISO 8601 date. For the formats that you can use, see General information.
`INVALID_CRON`	A schedule isn't a valid cron expression.
`INVALID_SORT`	`sortOrder` isn't `asc` or `desc`.
`UNSUPPORTED_VALUE`	A field has a value that the endpoint doesn't support. `params.allowed` lists the values that you can use.
`MUTUALLY_EXCLUSIVE_FIELDS`	You sent fields that can't go together. `params.fields` lists them: send only one.
`INVALID_PACKAGE_ID`	The package ID has characters that aren't allowed. `params.characters` lists them.
`INVALID_JSON`	A value in the JSON body has the wrong type, or the body can't be read.
`INVALID_QUERY_CRITERIA`	The query criteria of a search or a report aren't valid.
`UNKNOWN_QUERY_FIELD`	A query rule, or a `filter.*` parameter of a search, uses a field that doesn't exist. `params.field` names it.
`OPERATOR_NOT_ALLOWED`	A query rule uses an operator that doesn't work on its field. `params.operator` and `params.field` name them.
`METADATA_SCHEMA_UNKNOWN`	The archive doesn't know the metadata schema. `params.schema` holds its namespace.
`METADATA_INVALID`	A metadata document doesn't match its schema. `details` lists each problem, with the JSON pointer of the field in `field`.
`METADATA_FIELD_NOT_SET`	The package doesn't have a value for the metadata field. `params.field` and `params.packageId` name them.
`REPORT_FORMAT_MISMATCH`	The report type doesn't support the output format. `params.reportType` and `params.format` name them.

The archive only checks metadata documents against their schema in environments where that's turned on, and it's off by default. Everywhere else, you don't get METADATA_INVALID.

Request too large (413)

`reason`	What it means for you
`BODY_TOO_LARGE`	The request body is larger than the maximum size.
`STRING_TOO_LARGE`	One value in the JSON body is longer than the maximum length.

For the limits, see General information.

Authentication errors (401)

`reason`	What it means for you
`AUTHENTICATION_FAILED`	The request has no token, or the token has expired, isn't valid, or has no `tenant` claim. Get a new token, and try again.
`BACKEND_REJECTED_TOKEN`	The archive rejected your token after the API accepted it. Get a new token. If it keeps happening, ask Docbyte.

To get a token, go to Authentication.

Permission errors (403)

`reason`	What it means for you
`PERMISSION_DENIED`	You can't do this. Your client doesn't have the role that the endpoint needs, it doesn't have the permission on the package, or the `tenant` header names a tenant that it can't work in.
`DOCUMENT_ACCESS_DENIED`	Your client can find the package, but it isn't allowed to open it. `params.packageId` names the package.
`WEBHOOK_CLIENT_MISMATCH`	An Adobe Acrobat Sign webhook call came with a client ID that doesn't match the one set up for your archive.

Not found (404)

`reason`	What it means for you
`RESOURCE_NOT_FOUND`	The path or the resource doesn't exist, or your client can't see it.
`PACKAGE_NOT_FOUND`	No package has the ID in `params.packageId`.
`PACKAGE_SET_NOT_FOUND`	No package set has the ID in `params.packageSetId`.
`USER_NOT_FOUND`	No user has the ID in `params.userId`.
`ROLE_NOT_FOUND`	No role has the name in `params.role`.
`SEARCH_CONFIG_NOT_FOUND`	The search configuration doesn't exist.
`SCHEDULE_NOT_FOUND`	No preservation schedule has the ID in `params.scheduleId`.
`AUDIT_EVENT_NOT_FOUND`	The audit trail has no event with the ID in `params.eventId`.
`EXECUTION_NOT_FOUND`	No running or finished job has the ID in `params.executionId`, for example a DIP export.
`CONTENT_NOT_FOUND`	The file, the download link, or the uploaded file that you refer to doesn't exist.
`METADATA_TEMPLATE_NOT_FOUND`	The archive has no metadata template for the schema in `params.schema`.

Conflicts (409)

`reason`	What it means for you
`STATE_CONFLICT`	The action doesn't fit the current state of the resource, for example a review of a deletion list that isn't ready for review.
`USER_ALREADY_EXISTS`	A user with this username already exists.
`SUBMISSION_ALREADY_EXISTS`	The package already has a submission with this name. Use a new file name.
`PACKAGE_ALREADY_TRANSFERRED`	The package was already transferred to the tenant in `params.targetTenantId`.
`RETENTION_RULE_IN_USE`	You can't delete the retention rule, because packages still use it.
`LEGAL_HOLD_ACTIVE`	The package is under a legal hold, so you can't change it.
`RETENTION_ACTIVE`	The package is under retention, so you can't change it.
`METADATA_NOT_READY`	The archive is still processing the package, so it can't update single metadata fields now. Try again in a moment, or send the complete metadata document instead.

Gone (410)

`reason`	What it means for you
`CONTENT_LINK_EXPIRED`	The download link has expired. To get a new link, get the package again with the `representations` enricher.

Range not satisfiable (416)

`reason`	What it means for you
`RANGE_NOT_SATISFIABLE`	The `Range` header asks for bytes outside the file.

Service unavailable (503)

`reason`	What it means for you
`BACKEND_UNAVAILABLE`	The archive is unavailable for a moment. Try again later. The response has no `Retry-After` header, so wait a little longer after each attempt.

Server errors (500)

`reason`	What it means for you
`INTERNAL_ERROR`	Something went wrong in the API.
`BACKEND_ERROR`	The archive couldn't process the request.
`EXTERNAL_SERVICE_ERROR`	A service outside the archive, such as an e-signature service, couldn't process the request.

Reasons in an ingest status

An ingest runs after the call returns, so a failed ingest doesn't come back as an HTTP error. Instead, the SIP and the ingest status get a failureReason field. It can hold the reasons above that apply, such as SUBMISSION_ALREADY_EXISTS, PERMISSION_DENIED, and CONTENT_NOT_FOUND, and these reasons that only appear here:

SIP_INVALID: the package isn't a valid SIP.
PROFILE_DISABLED: the archiving profile is turned off.
PROFILE_NOT_FOUND: the archiving profile doesn't exist.
INGEST_FAILED: the ingest failed for another reason.

To follow an ingest, go to Ingest API.

Errors on the v1 and x19512 APIs

The v1 and x19512 APIs keep their older error body, with only code and message, and no X-Error-Id header:

JSON

{
  "code": "NO_PERMISSION",
  "message": "No permissions to perform this action"
}

They also keep their older codes: VALIDATION_ERROR, JSON_TOO_LARGE, NOT_AUTHORIZED, NO_PERMISSION, NO_ACCESS, NOT_FOUND, CONFLICT, and EXCEPTION. For a server error, the message holds the error ID, for example Internal server error. Error id: 3f6c2a9e-8b41-4d7a-9c55-2e1f0b7d4a10.