Skip to main content
The v2 standard resources of the public API answer their errors with an RFC 9457 problem details body, Content-Type: application/problem+json (the few exceptions are in Errors that are not problem details):
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"]). A body that is not valid JSON or not sent as application/json, a body nested more than about 1,000 levels deep (too_deep), and an id in the URL that is not a UUID, answer this code too.
The type and msg of each problem use two vocabularies. Here, for the request as a whole, they keep the names of earlier API versions (value_error.missing, field required). Inside a record of BULK_RECORDS_REJECTED (SCHEMA_INVALID) they are the current ones (missing, Field required, greater_than). Match on loc and error_code, which are stable, rather than on msg.

BULK_RECORDS_REJECTED — 422

One or more records of a bulk request are invalid, so nothing was written (see All or nothing). 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 the page of each route for its record codes: Create Wastes, Create Facilities, Create Logistics Requests (v2), Create Logistic Hubs (v2), the invoice routes (electricity, fuels, refrigerants, water, district heating, district cooling, process), Create Purchases, Create Purchase Suppliers, Classify Purchase Suppliers, Create Vehicles, Create Employees, Create Commuting Periods (and Replace Commuting Response, whose body is its record 0), Create Vehicle Consumptions, Create Workforce Employees, Create Workforce Trainings, Create Workforce Absences, Create Business Travels, Create Hotel Stays, Create Freight Transports, Create Sold Products, Create Use of Sold Products, Create Waste Water Treatments and the bulk deletes (wastes, invoices, purchases, purchase suppliers, vehicles, vehicle consumptions, employees, commuting periods, workforce employees, workforce trainings, workforce absences, business travels, hotel stays, freight transports, sold products, uses of sold products, waste water treatments, facilities). The record codes shared by every route: A job can also fail single records after the 202, while calculating or deleting them: their job items end failed with CALCULATION_FAILED (the emissions could not be calculated) or DELETE_FAILED (the entity was already gone, or it could not be deleted: check whether it still exists; if it does, send its id in a new delete job, and if that fails too, or for a vehicle or a facility, contact support with the job id), or JOB_TIMED_OUT (the job made no progress for 4 hours and was closed with the record still pending: see A job that does not finish). Some routes give the reason with a code of their own instead: a logistics leg fails with NO_DISTANCE, DISTANCE_CALCULATION_ERROR, AIR_DISTANCE_NOT_FLOWN and the other codes of Why a leg failed to calculate, a logistics delete keeps a leg sent again or edited after the delete job was created and fails it with UPDATED_AFTER_DELETE_REQUESTED (Deleting and sending again), a purchase, a business travel or a freight transport priced by its amount of money with EXCHANGE_RATE_NOT_FOUND when the rate of its currency to EUR cannot be had for its date (error_params.field names the currency field: unit_id for a purchase, currency_unit_id for the other two), a purchase supplier being classified with EXCHANGE_RATE_NOT_FOUND when every one of its purchases that ended in error lacked an exchange rate, or CALCULATION_FAILED otherwise (error_params.purchases_failed counts them), a business travel with TRANSPORT_MODE_INVALID_FOR_ROUTE or DISTANCE_CALCULATION_ERROR (How it works), a freight transport with DISTANCE_CALCULATION_ERROR when the distance of one of its sections cannot be had (How it works), and a commuting record with DISTANCE_CALCULATION_ERROR when the distance of one of its modes cannot be had (How it works).

WEBHOOK_ENDPOINT_LIMIT_REACHED — 422

Your organization already has 20 webhook endpoints, the most it can have. Disabled endpoints count too: delete one you no longer use (disabling it does not free a place), then create the new one. See Create Webhook Endpoint.

FILE_TOO_LARGE — 413

POST /v2/files takes files of up to 25 MB. Upload a larger one through the presigned flow, which takes up to 100 MB. Nothing was stored.

UPLOAD_TIMEOUT — 408

The body of the upload did not arrive within 120 seconds. Nothing was stored. Retry with the same Idempotency-Key, or use the presigned flow on a slow connection.

UPLOADS_BUSY — 503

Too many uploads are in progress, counted from the first byte of each body: on the server that took the request, or from your organization (4 at once per server). Nothing was read or stored. Retry with the same Idempotency-Key after the seconds in Retry-After.

FILE_CONTENT_NOT_ALLOWED — 422

The bytes of the file are not what its extension says, such as a PNG named .pdf, HTML in a .txt or in an .xls, or an Office file that expands past the limit. Nothing was stored. Send it with its real extension, or export it again: Upload a File (v2) says what each extension must hold.

FILE_EMPTY — 400

The file you sent to POST /v2/files has no bytes. Nothing was stored.

FILE_LIMIT_REACHED — 403

The organization is on the free plan and has as many files as the plan allows. Nothing was stored. Delete files you no longer use, or ask an admin of the organization to review its plan with Dcycle.

SHEET_REQUIRED — 422

The workbook has several tabs and you did not say which to import. error_params.sheets lists them, each with name, rows, date_min and date_max. Send again with sheet_name. No session was opened. See Open an Import Session.

SHEETS_COLUMNS_DIFFER — 422

You asked for several tabs to be read as one table (sheet_names), and one of them has a column the first tab does not have by name that could not be matched to one of the first tab’s columns. error_params gives the sheet that differs, its columns and the expected_columns. No session was opened. Rename that tab’s columns as the first tab’s, leave that tab out, or import it in its own session with sheet_name. See Open an Import Session.

FILE_NOT_IMPORTABLE — 422

No import session can be opened from this file: the template does not exist, the sheet_name (or one of the sheet_names) is not a tab of the workbook, tabs were asked of a CSV, the file is not an uploaded spreadsheet, its bytes cannot be read as one, or it has no rows. Check the template_id, the tabs and the file; retrying the same request does not help. See Open an Import Session.

IMPORT_FILE_TYPE_NOT_SUPPORTED — 400

The importer reads csv, xlsx and xls, and this file is none of them.

IMPORT_FILE_TOO_LARGE — 400

This spreadsheet is larger, or expands to more, than the importer reads. Split it and upload each part.

IMPORT_TEMPLATE_NOT_IN_PLAN — 403

The organization’s plan does not import this template. Ask an admin of the organization to review its plan with Dcycle.

IMPORT_HEAVY_OPERATION_BUSY — 503

The importer is reading other files at its limit. Nothing changed. Retry in some seconds.

IDEMPOTENCY_KEY_REUSED — 422

The Idempotency-Key was already used in your organization in the last 24 hours with a different body, or on another route. Use a new key for a new batch, or resend the original body unchanged to the original route. A key used more than 24 hours ago is free again: a request with it is a new one. See The Idempotency-Key.

IDEMPOTENCY_KEY_IN_PROGRESS — 409

Another request with the same Idempotency-Key is being processed, typically because you retried after a timeout. This request wrote none of its records. Retry with the same key and body after Retry-After seconds: you get the result of the request that went through.

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. A URL under one of these resources that matches no route (e.g. /v2/wastes/typo) answers it too, with detail: "Not Found".

METHOD_NOT_ALLOWED — 405

The URL exists, but not with that method (e.g. PUT /v2/wastes). Use the method on the route’s page.

REQUEST_BODY_TOO_LARGE — 413

The request body is over 100 MB. The limit applies to every route, with or without a Content-Length, and the request is refused as soon as it passes it. Send less data in one request.

ORG_ADMIN_REQUIRED — 403

Only organization admins can do this. Webhook endpoints need the predefined Administrator role; a custom role with member management is not enough.

API_KEY_SCOPE_DENIED — 403

The key is read-only and the request writes. A read-only key can send GET requests and the queries sent as POST (downloads, reports, total impacts). Use a key with write access for this request.

LOGGED_USER_NOT_MEMBER — 403

The person who created the API key is not an enabled member of the organization in x-organization-id: a key acts as its creator, so it stops working in an organization the creator leaves or when the creator’s user is disabled. Use a key created by a member of that organization.

VIEWER_CANNOT_WRITE — 403

The request writes, and the person behind it has the Viewer role in the organization in x-organization-id. With an API key, that is the key’s creator: a key can write only while its creator may. Reads still work. Ask an admin of the organization for a role that can write, or use a key created by a member who has one.

PLAN_FEATURE_NOT_INCLUDED — 403

The plan of the organization in x-organization-id does not include this resource: the organization is on the free plan, with no paying group above it. Retrying does not help, and neither does a dry run. Ask an admin of the organization to review its plan with Dcycle. What the free plan includes lists the v2 routes it keeps.

AUTHENTICATION_REQUIRED — 401

The request has no credentials: send your API key in x-api-key and your organization id in x-organization-id (see Authentication). A request with an x-api-key gets the key’s own reason instead: INVALID_API_KEY, ORGANIZATION_ID_REQUIRED, API_KEY_ORG_MISMATCH, API_KEY_EXPIRED, API_KEY_SCOPE_DENIED, API_KEY_NO_OWNER or LOGGED_USER_NOT_MEMBER.

AUTH_REQUIRED — 401

The same as AUTHENTICATION_REQUIRED: no credentials. Handle them alike.

CREDENTIALS_REQUIRED — 401

The same as AUTHENTICATION_REQUIRED: no credentials. Handle them alike.

INVALID_API_KEY — 401

The x-api-key is not an active key: it is mistyped, or it was revoked. It is also the answer when x-organization-id is not a UUID. Check the key in Company settings → API Keys and the organization id.

API_KEY_EXPIRED — 401

The key has expired (keys last 90 days unless another life was chosen when creating them). Create a new key in Company settings → API Keys, replace it in your integration and revoke the old one. The same list shows when each key expires, and the person who created the key is emailed 14 and 3 days before and once it has expired: rotate before that date.

API_KEY_ORG_MISMATCH — 401

The key is valid but belongs to another organization: x-organization-id must be the key’s organization or one of its subsidiaries. On the /v1 and /v2 routes the answer is the same whether or not that organization exists. Send the id of the key’s organization, or use the key of the other one.

API_KEY_NO_OWNER — 401

The key was created before keys had an owner (a key acts as the member who created it), so it cannot act as anyone. Create a new key in Company settings → API Keys. The legacy /api/v1/... routes answer 401 with the message This API key has no creator on record, ....

USER_ID_REQUIRED — 400

The same as API_KEY_NO_OWNER: a key without an owner. Create a new key.

ORGANIZATION_ID_REQUIRED — 400

The x-organization-id header is missing or empty. Send the id (UUID) of the organization the request acts on.

INVALID_PARTNER_HEADER — 400

The x-partner header is not a plain partner name: it may only contain letters, digits, - and _ (up to 64 characters). Send your organization’s partner, such as dcycle, or leave the header out.

ORGANIZATION_NOT_FOUND — 404

x-organization-id is a UUID, but no organization has it. Check the id. With an API key on the /v1 and /v2 routes, an organization the key cannot act on answers API_KEY_ORG_MISMATCH instead, whether or not it exists.

TOO_MANY_REQUESTS — 429

Rate limited. Wait Retry-After seconds. See Rate limits. On POST /v2/logistics/requests it also means too many requests at the same time with one key (detail: "Too many concurrent requests"). On a webhook test or retry it means your organization already has two of them in flight; wait Retry-After (20 seconds). That answer still carries your key’s RateLimit headers, which do not count this limit.

Errors that are not problem details

A few answers come from layers in front of the API and keep another shape, so check Content-Type before parsing:
  • 401 with {"detail": "INVALID_OR_EXPIRED_TOKEN"} (or INVALID_AUTHORIZATION_HEADER, INTERNAL_ERROR, USER_NOT_FOUND): the request carried an Authorization header, which is for people signed in to Dcycle. It is checked first, so a valid x-api-key fails too. Do not send Authorization with an API key, and never put the key in it.
  • 500 with a plain-text Internal Server Error and no request_id: an unexpected error on our side. Retry later; if it persists, tell support the route and the time.
  • 502, 503 or 504 from the load balancer or a database timeout, as text, HTML or {"detail": "..."}: retry with backoff, resending a bulk write with the same Idempotency-Key.
  • 307 to the same URL without the trailing slash (e.g. POST /v2/wastes/): call the URL without it.
  • 404 with {"detail": "Not Found"}: the resource name itself is misspelled (e.g. /v2/waste), so the URL is outside these resources. Check the path.

Handling errors

Python