Preview. This API will change in v1.0.0. Breaking changes are announced in the release notes with migration steps before they apply, unless a security or legal issue needs an immediate change; then we announce it there as soon as we can.
Errors
An error returns a JSON body with a plain message in error:
{ "error": "Missing required field: blNumber" }
Many errors also carry a stable code, and an error about the Terms can carry version, the Terms version in force. Match on the status and the code, not on the text of error.
| Status | Meaning | Codes you may see |
|---|---|---|
| 400 | The body is not valid JSON, or a webhook or key request is missing a field or names a URL that is not allowed | webhook_url_not_allowed |
| 401 | No key, an unknown key or a revoked key | |
| 403 | No Terms acceptance stands behind the request: the key was created before DocuShield recorded acceptance on keys, or the person behind it has not accepted the current Terms | api_key_policy_unbound, policy_not_accepted |
| 404 | No such record, webhook or key in your organisation | |
| 413 | The document sent to POST /verify is larger than 16 MB | |
| 422 | A required field is missing, or a value is not allowed. governing_law_not_permitted means the body names a governing law other than the one DocuShield accepts; the error text names it | governing_law_not_permitted |
| 429 | Too many requests: POST /verify allows 30 a minute per client; wait and try again | rate_limited |
| 500 | Unexpected failure | |
| 501 | The API cannot do this: filing a transferable record | transferable_issuance_unavailable |
| 503 | A service DocuShield depends on is down; try again later | auth_check_failed, policy_check_failed, policy_version_unavailable |
Some unexpected database failures return the framework's default error page instead of JSON. Treat any 5xx as temporary and try again after a pause.
Retrying POST /ebl
POST /ebl has no idempotency key, and DocuShield does not refuse a second record with the same blNumber. If a call fails or times out, look for your blNumber in GET /ebl before you send it again, or you may file the record twice.
Rate limits
Some endpoints are rate limited. POST /api/v1/verify allows 30 requests a minute per client; above that it returns 429 with code rate_limited. Other limits will be announced in the release notes before they apply.