Errors - Dcycle Platform Docs

The v2 resources of the public API (/v2/wastes, /v2/ingest-jobs, /v2/webhook-endpoints) answer every error with an RFC 9457 problem details body, Content-Type: application/problem+json:

{
  "type": "https://code.dcycle.io/api-reference/errors#BULK_RECORDS_REJECTED",
  "title": "Unprocessable Content",
  "status": 422,
  "code": "BULK_RECORDS_REJECTED",
  "detail": "2 of the submitted records are invalid; nothing was written.",
  "errors": [ { "source_row_index": 1, "error_code": "REFERENCE_NOT_FOUND", "error_params": { "field": "unit_id" } } ],
  "rejected": 2,
  "request_id": "b2248a31-0f1b-4a7d-83ce-b29bd5977b4c"
}

Field	Meaning
`code`	The stable key to branch on. Never parse `detail`.
`status`	The HTTP status, repeated in the body.
`title`	The status’ standard reason phrase.
`detail`	A sentence for people. It may change.
`errors`	What was wrong, when there is a list: validation errors (`loc`, `msg`, `type`) or rejected records.
`type`	A link to this page, to the code’s section.
`request_id`	Also in the `X-Request-ID` header. Quote it when you contact support.

Other members may appear for a given code (e.g. rejected). Ignore the ones you do not use. Older endpoints (/v1/...) keep their historical format: {"code": "...", "detail": "..."}, or {"detail": [...]} for validation errors.

Codes

REQUEST_VALIDATION_FAILED — 422

The request does not match the contract: a missing header (e.g. Idempotency-Key), a malformed body, a query value of the wrong type. errors lists each problem with where it is (loc, e.g. ["body", "records"]).

BULK_RECORDS_REJECTED — 422

One or more records of a bulk request are invalid, so nothing was written. rejected is how many, and errors lists them (up to 100) with source_row_index, your client_row_id, an error_code and error_params. See Create Wastes for the record codes.

IDEMPOTENCY_KEY_REUSED — 422

The Idempotency-Key was already used with a different body. Use a new key for a new batch.

NOT_FOUND — 404

The resource does not exist, or it belongs to an organization outside the one in x-organization-id: both cases answer the same, so ids cannot be probed.

ORG_ADMIN_REQUIRED — 403

Only organization admins can do this (e.g. manage webhook endpoints).

LOGGED_USER_NOT_MEMBER — 403

The API key’s user is not a member of the organization in x-organization-id.

TOO_MANY_REQUESTS — 429

Rate limited. Wait Retry-After seconds. See Rate limits.

Handling errors

Python

response = requests.post(url, headers=headers, json=body, timeout=60)
if response.headers.get("content-type", "").startswith("application/problem+json"):
    problem = response.json()
    if problem["code"] == "BULK_RECORDS_REJECTED":
        for record in problem["errors"]:
            print(record["source_row_index"], record["error_code"], record["error_params"])
    else:
        raise RuntimeError(f"{problem['code']}: {problem['detail']} (request {problem['request_id']})")

​Codes

​REQUEST_VALIDATION_FAILED — 422

​BULK_RECORDS_REJECTED — 422

​IDEMPOTENCY_KEY_REUSED — 422

​NOT_FOUND — 404

​ORG_ADMIN_REQUIRED — 403

​LOGGED_USER_NOT_MEMBER — 403

​TOO_MANY_REQUESTS — 429

​Handling errors