Error code index

400 Bad request

• Validation failed400

  The body or the query string failed schema validation.

  Fixdetails maps each invalid field to its messages. Fix the request; sending it again unchanged fails again.

  Extra properties: details

  Every endpoint that takes a body or query parameters
• invalid_idempotency_key400

  The Idempotency-Key header is empty or longer than 255 characters.

  FixSend 1–255 characters; a UUID per logical operation is ideal. See Idempotency.

  Any write (POST, PATCH, PUT)
• Body cannot be empty when content-type is set to 'application/json'400

  The request said Content-Type: application/json but sent no body.

  FixSend {} for a write without parameters (for example POST /passports/{id}/publish), or drop the header.

  Any write (POST, PATCH, PUT)
• No file uploaded400

  A document upload arrived without a file part.

  FixSend multipart/form-data with the file in a part named file.

  POST/models/{id}/documents
• Document type required400

  A document upload arrived without a type.

  FixAdd a type part, for example EU Declaration of Conformity.

  POST/models/{id}/documents

401 Unauthorised

• unauthorized401

  The API key is missing, malformed, unknown or revoked.

  FixSend Authorization: Bearer dpp_live_… (or dpp_test_…). A revoked key never comes back — create a new one under Organisation → API keys.

  Every /v1 endpoint except GET /openapi.json

402 Payment required

• plan_upgrade_required402

  Your plan does not include this. API access itself (erp_api) is on every plan; publishing needs a paid plan and supplier requests need Growth.

  Fixfeature names what is missing and requiredPlan the plan that includes it. Upgrade, then retry.

  Extra properties: feature requiredPlan

  POST/modelsPOST/itemsPOST/items/batchPOST/passports/{id}/publishPOST/passports/publishPOST/upload-linksPOST/webhooks
• paused_on_maintenance402

  The organisation is on the Maintenance plan, which keeps published passports resolving but pauses creating and publishing.

  Fixfeature names what is paused. Return to a production plan to resume; reads and exports keep working.

  Extra properties: feature

  The same operations as plan_upgrade_required

403 Forbidden

• insufficient_scope403

  The key is valid but lacks the scope this call needs: read for GET (and POST /models/validate), write for everything else.

  FixUse a key with the write scope for writes. Scopes are fixed when a key is created; see Authentication.

  Any write (POST, PATCH, PUT)
• method_not_allowed_for_api_keys403

  A DELETE was sent with an API key. Records are never deleted over the API — a passport must stay available for ten years.

  FixRecycle or change the status instead, or delete in the app, where deletions are audited. See Why there is no DELETE.

  Any DELETE

404 Not found

• not_found404

  Also spelled Not found

  No record with this id in your organisation. Records of other organisations are indistinguishable from records that do not exist. Older routes spell it Not found; both share this entry. Bulk endpoints also use not_found per row, with the response itself succeeding.

  FixCheck the id and that the key belongs to the organisation that owns the record. Branch on the status, not on the spelling.

  GET/passports/{id}/eventsGET/documents/{id}Webhook endpoint operationsGET/models/{id}GET/items/{id}GET/passports/{id}POST/passports/publish(per row)POST/passports/bulk-lifecycle(per row)POST/passports/import-updates(per row)
• Model not found404

  modelId (or the model in the path) does not name a model in your organisation.

  FixCreate the model first, or use the id POST /models returned.

  POST/itemsPOST/items/batchPOST/models/{id}/documentsPOST/upload-links/{id}/accept
• route_not_found404

  The method and path are not part of the API — usually a typo, a missing /v1, or the wrong method.

  Fixmessage repeats what was called. Compare with the API reference.

  Any unknown /v1 path
• Passport not found404

  The public resolver has no published passport under this identifier: it was never issued, or it is still a draft.

  FixPublish the passport. A fabricated identifier and an unpublished one answer the same, on purpose.

  GET/p/{uniqueIdentifier}GET/p/{uniqueIdentifier}.jsonld

409 Conflict

• organisation_frozen409

  The organisation is frozen and read-only. Published passports keep resolving and data stays exportable.

  FixfrozenAt and reason say when and why. Reads and exports keep working; contact us to reactivate.

  Extra properties: frozenAt reason

  Any write (POST, PATCH, PUT)
• identifier_taken409

  The uniqueIdentifier you brought over already exists. An identifier resolves to exactly one battery and is never reused.

  FixLook the battery up with GET /passports?unique_identifier=… instead of creating it again.

  POST/items
• idempotency_in_progress409retry

  The first request with this Idempotency-Key is still running.

  FixRetry shortly with the same key; you will get the stored answer once the first request finishes.

  Any write (POST, PATCH, PUT)
• Passport has ceased (recycled)409

  The battery was recycled, so its passport has ceased (Art. 77(8)) and can no longer be published or change status.

  FixNothing to retry. A recycled passport is final; the resolver answers 410 for it.

  POST/passports/{id}/publishPATCH/passports/{id}/status
• no_model409

  The supplier request is not attached to a model, so there is nowhere to accept its values into.

  FixCreate supplier requests with a modelId when you mean to accept values into a model.

  POST/upload-links/{id}/accept

410 Gone

• Passport has ceased (battery recycled)410

  Also spelled Passport has ceased

  The battery was recycled and its passport has ceased. The JSON-LD resolver answers Passport has ceased for the same case.

  FixShow the reader that the battery was recycled — 410, unlike 404, means the passport existed.

  GET/p/{uniqueIdentifier}GET/p/{uniqueIdentifier}.jsonld

413 · 415 Payload too large, unsupported type

• File too large413

  The document is larger than 25 MB.

  FixCompress or split the document; the limit is per file.

  POST/models/{id}/documents
• Unsupported file type415

  The document is not a PDF, JPEG or PNG.

  FixConvert it to PDF, which is what market surveillance authorities expect for declarations and reports.

  POST/models/{id}/documents
• Unsupported Media Type415

  The request body has a Content-Type the API does not parse.

  FixSend application/json, or multipart/form-data for document uploads.

  Any write (POST, PATCH, PUT)

422 Unprocessable

• publish_blocked422

  The passport cannot be published yet: the battery has no place of manufacture, or the model is missing required data for its category.

  Fixblockers lists each reason (missing_place_of_manufacture, model_incomplete with the missing fields). Fill them, then publish again. Check ahead with GET /models/{id}/completeness.

  Extra properties: blockers

  POST/passports/{id}/publish
• invalid_identifier422

  A uniqueIdentifier you brought over breaks the identifier rules (characters, length, format).

  Fixviolations lists each broken rule and message explains them. Omit uniqueIdentifier to have one minted for you.

  Extra properties: violations

  POST/items
• date_required422

  The putInService lifecycle event needs an in-service date.

  FixAdd date (ISO 8601) to the request.

  POST/passports/bulk-lifecycle
• invalid_webhook_url422

  The webhook URL is not acceptable: not https, credentials in the URL, a host that does not resolve, or one that resolves to a private address.

  Fixmessage names the problem. Use a public https URL; authenticate deliveries with the signature, not the URL.

  POST/webhooksPATCH/webhooks/{id}
• idempotency_key_reused422

  This Idempotency-Key was already used, within 24 hours, for a request with a different method, path or body.

  FixUse a new key for a new request. Reuse a key only to retry the exact same request.

  Any write (POST, PATCH, PUT)
• nothing_to_accept422

  None of the fields you asked to accept were proposed by the supplier on this request.

  FixRead the request first (GET /upload-links) and accept only fields it carries.

  POST/upload-links/{id}/accept

429 · 5xx Rate limits and server errors

• Rate limit exceeded, retry in <time>429retry

  More requests than the key’s per-minute limit: 600 for live keys, 60 for test keys.

  FixWait for the seconds in retry-after, then retry. See Rate limits.

  Every endpoint
• Internal server error500retry

  Something failed on our side.

  FixRetry with backoff and the same Idempotency-Key — a 5xx is never stored, so the retry runs again. Quote request_id if you contact us.

  Every endpoint

207 Per-row codes in bulk responses

Bulk endpoints answer for every row. When any row fails the response is 207, and each failed row carries ok: false and one of these codes in error. not_found is also used per row; it is documented above.

• ceasedper row

  The passport in this row was recycled, so it cannot be published.

  FixDrop the row; nothing will change its outcome.

  POST/passports/publish
• missing_place_of_manufactureper row

  The battery in this row has no place of manufacture. The EU registry refuses a passport without one.

  FixSet placeOfManufacture on the battery, then publish the row again. Also appears as a blockers[].reason of publish_blocked.

  POST/passports/publish
• model_incompleteper row

  The model is missing data required for its battery category; message names it.

  FixFill the fields GET /models/{id}/completeness lists, then publish again. Also appears as a blockers[].reason of publish_blocked.

  POST/passports/publish
• already_recycledper row

  The passport in this row has ceased (recycled), so the change was skipped.

  FixNothing to do; the skip is reported so you can see it happened.

  POST/passports/bulk-lifecyclePOST/passports/import-updates
• nothing_to_changeper row

  The row matched a battery but none of its values differ from what is stored.

  FixNothing to do. Send only rows that change something to keep the result short.

  POST/passports/import-updates