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 sameIdempotency-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 sameIdempotency-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 toPOST /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, thesheet_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 readscsv, 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
TheIdempotency-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 sameIdempotency-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 inx-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 aContent-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 sendGET 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 inx-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 inx-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 inx-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 inx-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 asAUTHENTICATION_REQUIRED: no credentials. Handle them alike.
CREDENTIALS_REQUIRED — 401
The same asAUTHENTICATION_REQUIRED: no credentials. Handle them alike.
INVALID_API_KEY — 401
Thex-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 asAPI_KEY_NO_OWNER: a key without an owner. Create a new key.
ORGANIZATION_ID_REQUIRED — 400
Thex-organization-id header is missing or empty. Send the id (UUID) of the organization the request acts on.
INVALID_PARTNER_HEADER — 400
Thex-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. WaitRetry-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 checkContent-Type before parsing:
401with{"detail": "INVALID_OR_EXPIRED_TOKEN"}(orINVALID_AUTHORIZATION_HEADER,INTERNAL_ERROR,USER_NOT_FOUND): the request carried anAuthorizationheader, which is for people signed in to Dcycle. It is checked first, so a validx-api-keyfails too. Do not sendAuthorizationwith an API key, and never put the key in it.500with a plain-textInternal Server Errorand norequest_id: an unexpected error on our side. Retry later; if it persists, tell support the route and the time.502,503or504from the load balancer or a database timeout, as text, HTML or{"detail": "..."}: retry with backoff, resending a bulk write with the sameIdempotency-Key.307to the same URL without the trailing slash (e.g.POST /v2/wastes/): call the URL without it.404with{"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