DPP Agent docs

Errors

An error is a non-2xx status with a JSON body. The body always has error; the other members depend on where the error comes from.

{ "error": "Validation failed", "details": ["gtin: must be 8-14 digits", "category: must be one of textile, …"] }

error is a short description, not a fixed code list, except for the few codes named below. Branch on the HTTP status, and show error, message, detail and details to a person.

By status

400 — the request is wrong

error says what; for passport writes it is "Validation failed" and details is an array with one sentence per problem, for example:

  • gtin: must be 8-14 digits
  • granularity: must be one of model/variant/batch/item
  • granularity=item but serial is missing
  • category: must be one of … (the valid list is in the message)
  • tenant.economic_operator_id: not a valid LEI/GS1/PEPPOL identifier (publishing needs one)

401 — not signed in

  • { "error": "auth required", "message": "Provide either Authorization: Bearer <api_key> OR sign in via the SPA. …" } on the passport-writing endpoints.
  • { "error": "Authentication required" } on dashboard endpoints, which do not take an API key.

A key that is unknown, revoked or not of the form dpp_live_… is treated as no key.

402 — plan limit

Publishing would take the tenant over its plan's number of active passports. Drafts can still be created.

403 — not allowed

  • { "error": "tenant_mismatch", "message": "This API key belongs to another tenant." } — the request named a different tenant_id than the key's.
  • { "error": "Tenant admin or DPP Agent operator role required" } — signed in, but not an admin or editor of that tenant.
  • { "error": "ip_blocked" } — requests from this network are blocked.

404 — not found

The passport, tenant or job does not exist, or belongs to another tenant: a resource outside your tenant is reported as not found rather than forbidden.

409 — conflict

  • Deleting a passport that is not a draft.
  • Changing the category of a published passport.

410 — gone

The passport was withdrawn or archived. Its address keeps answering, with { "error": "DPP is no longer publicly resolvable", "status": "withdrawn" } for JSON and a page explaining it for browsers.

413 — too large

More than 1 000 items in POST /api/v1/dpps-batch or 1 000 product IDs in POST /api/v1/dppsByProductIds.

429 — too many requests

Always with Retry-After in seconds. Three sources:

  • API key quota: { "error": "quota_exceeded", "message": "Per-minute rate limit hit. …" } (or the daily quota).
  • Per-address limits on public endpoints: { "error": "Too many requests", "detail": "At most 60 requests a minute from one address. …", "retry_after_s": 23 }.
  • The resolver: a plain-text body.

See Rate limits.

500 — our error

error carries the message. Try again; if it persists, send the request and the time to support@dppagent.com.