Каталог кодов ошибок

Каждый неуспешный ответ API — RFC 9457 Problem Details с полем type, равным коду из этого каталога, и HTTP-статусом по типу ошибки: Validation 400, NotFound 404, Conflict 409, Failure 500. Ошибки валидации несут ещё errors — поле → причина.

Страница генерируется из реестра docs/api/error-codes.yaml бэкенда при сборке (218 кодов); править её руками бессмысленно — правьте реестр.

api

Код	Статус	Описание
api.rate_limited	429	Rate limit exceeded; retry after the indicated delay.
api.malformed_request	400	The request could not be read — malformed JSON, a wrongly typed field, a missing body, a missing required route or query parameter. The offending field, where one exists, is named in errors[0].field. Also carries 415 when the request has no Content-Type at all, the one non-400 status the framework raises for a request it cannot read.
api.unsupported_media_type	415	The request carried a Content-Type this endpoint does not accept (refused by routing before the endpoint ran); send application/json.
api.payload_too_large	413	The request body exceeds the server’s size limit.
api.request_body_incomplete	408	The request body ended before its declared length — typically a dropped connection mid-upload; the client should send the request again.
api.day_window_conflict	400	The request named both a tenant day (createdOn on the orders list, day on the trips list and the trip report) and an explicit window (createdFrom/createdTo, or from/to). Send one or the other — the day is turned into the tenant’s own local midnight-to-midnight window by the server.

apikeys

Код	Статус	Описание
apikeys.name_required	400	API key name is required.
apikeys.invalid_scope	400	API key scope is not in the allowed catalog.
apikeys.already_revoked	409	API key is already revoked.
apikeys.not_found	404	No API key with the given identifier in the current tenant.
apikeys.invalid_rate_limit	400	API key rate limit must be a positive number of requests per minute.
apikeys.rate_limit_above_max	400	API key rate limit exceeds the maximum allowed requests per minute.

artifacts

Код	Статус	Описание
artifacts.unsupported_type	400	Artifact content type must be image/png or image/jpeg.
artifacts.too_large	400	Artifact exceeds the maximum upload size.
artifacts.empty	400	Artifact file is empty.

audit

Код	Статус	Описание
audit.page.retired	400	The page parameter was removed when GET /api/audit moved to cursor paging (#755); it is refused rather than ignored, because a silently ignored page hands the caller page one and calls it page seven.
audit.cursor.invalid	400	The after cursor on GET /api/audit is not a cursor this server issued; answered rather than ignored, because treating it as “start from the top” would return page one under a Next button and read as the log having ended.

couriers

Код	Статус	Описание
couriers.duplicate	409	Concurrent sync for the same (Source, ExternalId).
couriers.notfound	404	No driver with the given identifier in the current tenant.
couriers.externalid.required	400	ExternalId is required for driver sync.
couriers.fullname.required	400	Driver full name is required.
couriers.phone.required	400	Driver phone is required.
couriers.email.invalid_format	400	Driver email is not a valid address.
couriers.tag.empty	400	Driver tag must not be empty.
couriers.archived	409	Driver is archived and cannot be updated.
couriers.shift.vehicle.required	400	Shift VehicleId is required.
couriers.shift.window.invalid	400	Shift FromUtc must be before ToUtc.
couriers.shift.overlap	400	Driver shifts must not overlap (one driver, one vehicle at a time — ADR-005).
couriers.user.directoryUnavailable	500	The identity provider could not be reached to verify the account, so the link is refused rather than created unverifiable (#564).
couriers.user.notFound	404	No identity with this id exists, so linking would produce a courier that can never sign in.
couriers.user.foreignTenant	400	The identity belongs to another tenant; one identity belongs to one tenant.
couriers.user.alreadyLinked	409	This courier is already linked to a different user.
couriers.user.notLinked	409	The courier is not linked to any user, so there is no link to remove.
couriers.privacy.versionMismatch	400	The acknowledged privacy-notice version must match the current notice version.
couriers.tag.skillUnknown	400	A courier tag is not in this tenant’s capability-skill schema.

drivers

Код	Статус	Описание
drivers.notLinked	403	The authenticated user is not linked to a courier profile.

geocoding

Код	Статус	Описание
geocoding.address_required	400	An address to geocode is required.
geocoding.address_not_found	404	The address could not be geocoded; place the point on the map by hand.
geocoding.failure.not_found	404	No geocoding failure is recorded under this key.
geocoding.retry.already_resolved	409	This address already resolves; a verdict is re-judged by the rules, not by a button.
geocoding.retry.warehouse_admin_only	403	A warehouse address is repaired by an administrator.

geozones

Код	Статус	Описание
geozones.requiredSkill.skillUnknown	400	A geo-zone required skill is not in this tenant’s capability-skill schema.

idempotency

Код	Статус	Описание
idempotency.inFlight	429	>-

import

Код	Статус	Описание
import.file.invalid	400	Import file must be a JSON array of row objects for the target entity.
import.rows.too_many	400	At most 1000 rows per import request.
import.row.invalid	200	Reported per row inside the 200 import response body; never an HTTP status.

invitations

Код	Статус	Описание
invitations.token.invalid	404	The invitation token is malformed or matches no invitation.
invitations.token.expired	400	The invitation has expired; a new one must be issued.
invitations.token.consumed	409	The invitation has already been used; the account exists and can sign in.
invitations.password.required	400	A password is required to complete the invitation.
invitations.password.policy	400	The password does not meet the realm policy; checked before the invitation is consumed, so the caller can retry with the same link.
invitations.password.weak	400	Keycloak rejected the password after the invitation was consumed (the realm policy is stricter than InvitationPasswordPolicy); the link is spent and a new invitation is needed.
invitations.keycloak.unavailable	500	Keycloak could not set the credential; the invitation was already consumed, so the link is spent and a new invitation is needed.
invitations.identity.missing	409	The invitation predates identity provisioning, so there is no Keycloak user to set a password on; the invitation is not consumed and a new one must be issued.
invitations.token.revoked	409	The invitation was replaced by a newer one (re-invite); only the latest link can be completed.

ministatuses

Код	Статус	Описание
ministatuses.name.invalid	400	MiniStatus name must be 1..64 characters.
ministatuses.duplicate	409	MiniStatus name already exists in this group (active, per tenant).
ministatuses.notFound	404	No MiniStatus with the given identifier in the current tenant.

orders

Код	Статус	Описание
orders.duplicate	409	Concurrent intake for the same (Source, ExternalId).
orders.notFound	404	No order with the given identifier in the current tenant.
orders.status.plannedOnAnotherTrip	409	The order’s current status came from a different trip, so this trip cannot recall it.
orders.status.changedSince	409	The order’s status has moved since the caller last saw it, so this write is stale.
orders.lines.required	400	An order requires at least one line.
orders.assignment.incomplete	400	A pre-assigned order names both a driver and a vehicle, or neither.
orders.assignment.driverNotFound	400	The assigned driver does not exist (or is archived) in this tenant.
orders.assignment.vehicleNotFound	400	The assigned vehicle does not exist (or is archived) in this tenant.
orders.no_lines	400	A manual order requires at least one line.
orders.coordinates.required	400	An order address needs coordinates.
orders.status.illegal	409	The requested order status transition is not legal from the current status.
orders.id_generation	409	Could not assign a unique manual order id; retry.
orders.notArchived	409	The order exists but is not archived, so it cannot be restored.
orders.price.invalid	400	Order price cannot be negative.
orders.unexpected	500	An order could not be processed due to an unexpected error (bulk intake item).
orders.rate_limited	429	API key rate limit exceeded; retry after the indicated delay.
orders.miniStatus.invalid	400	MiniStatus is required and must be ≤128 characters.
orders.miniStatus.unknown	400	MiniStatus is not an active entry of the tenant’s directory for the order’s current status group (FR18, ADR-014).
orders.externalId.required	400	ExternalId is required.
orders.planDeliveryPeriod.invalid	400	Delivery period end is before start.
orders.planPickupPeriod.invalid	400	Pickup period end is before start.
orders.return.relatedRequired	400	A Return order requires RelatedToOrderId.
orders.line.warehouseRequired	400	Each order line requires a WarehouseId (ADR-009).
orders.line.roleNotAllowed	400	Only a Rebox order may carry a line with the PickUp role; every other order type delivers its lines.
orders.line.roleImmutable	400	Line roles are fixed when the order is created; a re-sync cannot change them.
orders.lines.immutable	409	The order’s lines can no longer change — it is planned, on a trip, or already has delivery outcomes; cancel it or return it to intake first.
orders.line.productRequired	400	Each order line requires a ProductId.
orders.line.requestedQty.invalid	400	A line’s requested quantity must be positive.
orders.line.measure.invalid	400	A line’s weight or volume is negative.
orders.line.product.notFound	400	A line names a product that does not exist (or is archived) in this tenant.
orders.line.warehouse.notFound	400	A line names a warehouse that does not exist (or is archived) in this tenant.
orders.import.externalId.required	400	A row (or the first row of a group of rows) has no ExternalId, so it cannot be grouped into an order.
orders.import.unsupported_file	400	The uploaded file could not be read as an .xlsx workbook, or its header row is missing the ExternalId column.
orders.import.row.invalid	400	A row’s Type, Lat/Long, quantity, price, weight/volume or delivery window could not be parsed.
orders.import.product.notFound	400	A row’s ProductCode does not match the name of any active product in this tenant.
orders.import.warehouse.unconfigured	400	No active warehouse is configured for this tenant; create one before importing orders from Excel.
orders.import.warehouse.required	400	The tenant has more than one active warehouse, so the Warehouse column is required on the group’s first row.
orders.import.warehouse.unknown	400	The Warehouse column does not match the name of any active warehouse in this tenant.
orders.import.too_many_rows	400	The uploaded workbook has more data rows than the import allows.

payments

Код	Статус	Описание
payments.amount.invalid	400	Payment amount must be positive.
payments.currency.invalid	400	Payment currency must be a three-letter uppercase ISO code.

planning

Код	Статус	Описание
planning.trip_not_editable	409	Trip must be Confirmed to add/remove/move/reorder a line or reassign driver/vehicle.
planning.trip_not_confirmed	409	Trip must be Confirmed to start.
planning.trip_not_in_progress	409	Trip must be InProgress to complete.
planning.trip_has_open_stops	409	Trip still has open stops or owes a return leg; skip or finish them before completing it.
planning.invalid_reorder	400	Stop reorder must be a permutation that keeps return stops last.
planning.job_not_queued	409	Planning job must be Queued to start.
planning.job_not_running	409	Planning job must be Running to complete or fail.
planning.job_already_running	409	A planning job is already in flight for this tenant.
planning.job_orders_required	400	A planning job must target at least one order.
planning.job_invalid_window	400	Planning window ToDate must not be earlier than FromDate.
planning.job_timed_out	503	The run was cancelled by the message execution timeout on its last delivery attempt and ended Failed instead of being redelivered indefinitely; re-run the job.
planning.constraints_violated	400	A trip broke a planning constraint whose specific code was not carried through; the fallback ReasonCode when a proposal is rejected without one.
planning.driver_daily_budget_exceeded	400	The driver’s remaining shift cannot hold this trip; the post-merge trim keeps the subset serving the most orders and demotes the rest to Unplanned.
planning.order_not_found	404	No planning-side order with that id exists in this tenant.
planning.order_not_in_planning	409	The order is not currently in planning, so it cannot be returned to intake or placed on a trip.
planning.order_on_trip	409	The order sits on a trip and cannot be returned to intake; remove it from every trip first.
planning.trip_no_lines	400	A trip must contain at least one order line.
planning.capacity_exceeded	400	An order line does not fit any compatible compartment’s remaining capacity.
planning.skill_unmatched	400	An order line requires skills no compartment provides.
planning.line_missing_dimensions	400	An order line is missing weight or volume and cannot be capacity-validated.
planning.multi_warehouse_violation	400	The trip’s warehouses violate the tenant multi-warehouse policy.
planning.order_line_already_assigned	409	This order line is already assigned to a trip.
planning.trip_not_found	404	Trip not found.
planning.trip_not_active	409	Trip must be Confirmed or InProgress to add a return stop.
planning.order_not_plannable	400	This order line cannot be planned (missing order, archived, terminal status, or unsupported order type).
planning.invalid_policy	400	The planning policy is invalid - a negative radius, WithinRadius without a positive radius, a stop, break or reload limit out of range, or a new default return warehouse that does not exist, is archived or belongs to another tenant (field defaultReturnWarehouseId).
planning.trip_not_stuck	409	Recording a stop for the driver is only for a trip whose day has already passed — on a current trip the driver is still the one closing stops.
planning.job_not_found	404	Planning job not found.
planning.sync_conflict_not_found	404	The offline-sync conflict does not exist in this tenant, so it cannot be marked as reviewed.
planning.job_not_cancelable	409	Job must be Queued or Running to cancel.
planning.no_zone	400	A destination point falls in no geo-zone and cannot be auto-planned.
planning.no_available_driver	400	No zone-assigned driver with a suitable vehicle is available for the planning window.
planning.assigned_pair_unavailable	400	The driver or vehicle the order was pre-assigned to is unknown or archived; the order was not planned.
planning.trip_concurrentModification	409	The trip was modified concurrently; reload and retry.
planning.driver_unavailable	400	The chosen driver is inactive or archived.
planning.stop_outside_zone	400	A stop falls in no geo-zone.
planning.driver_not_in_zone	400	The driver is not assigned to the stop’s geo-zone.
planning.driver_skill_unmatched	400	The driver lacks a skill the geo-zone requires.
planning.driver_off_shift	400	The driver has no shift with the chosen vehicle today.
planning.mixed_kind_not_allowed	400	A vehicle without the combined-runs capability cannot serve more than one stop kind in a route.
planning.rebox_not_splittable	400	A Rebox order is one swap at one visit, so all of its lines must ride the same trip.
planning.rebox_split	409	Part of this Rebox order is already on a live trip; the remaining lines need manual re-assembly onto that same trip.
planning.load_prefix_violated	400	Loading stops must precede every other stop in the route.
planning.warehouse_not_geocoded	400	A warehouse a line needs loaded from has no usable geocoded location.
planning.vehicle_snapshot_missing	400	The vehicle a trip’s load must be validated against has no planning snapshot.
planning.vehicle_archived	400	An archived vehicle cannot be chosen for a trip.
planning.vehicle_no_compartments	400	The vehicle has no compartments configured, so its load cannot be validated.
planning.time_window_violated	400	The order’s delivery time window cannot be met in this planning run.
planning.not_fitted_in_routes	400	The order fits this vehicle on every local rule but did not fit the routes of this planning run.
planning.no_solution_found	400	The planner found no solution for this order’s group within its time budget; split the batch or run planning again.
planning.routing_unavailable	503	The road-routing service returned no complete matrix; the planning run was aborted instead of falling back to straight-line distances.

products

Код	Статус	Описание
products.requiredSkill.skillUnknown	400	A product required skill is not in this tenant’s capability-skill schema.

reports

Код	Статус	Описание
reports.range.invalid	400	The report window must end after it starts.

statistics

Код	Статус	Описание
statistics.daily.daysOutOfRange	400	The dashboard daily series accepts between 1 and 31 days.
statistics.tenant.invalid	400	The ambient tenant id on a dashboard request is not a valid GUID.
statistics.tenant.notFound	404	The dashboard request’s tenant does not exist in the registry.

tags

Код	Статус	Описание
tags.duplicate	409	A tag with the same name already exists.
tags.notFound	404	No tag with the given identifier in the current tenant.
tags.name.invalid	400	Tag name must be 1..64 characters.
tags.color.invalid	400	Tag color must match #RRGGBB.

tenancy

Код	Статус	Описание
tenancy.missing	400	No tenant could be resolved from the X-Tenant-Id header or the tenant_id claim.

tenants

Код	Статус	Описание
tenants.skills.value.invalid	400	Each capability skill must be 1-64 chars, trimmed, non-blank.
tenants.skills.duplicate	400	Capability skills must be unique (case-insensitive).
tenants.skills.too_many	400	At most 100 capability skills are allowed.
tenants.invitation.baseUrlNotConfigured	500	Invitations:AdminBaseUrl is unset or is not an absolute http(s) URL, so no invitation link can be issued.
tenants.users.role.invalid	400	The role filter on GET /api/users names something that is not a user role; the filter is parsed rather than bound so the shared UserRole schema stays free of a null member.
tenants.users.status.invalid	400	The status filter on GET /api/users names something that is not a user status; parsed for the same reason as the role filter.
tenants.lifecycle.state.invalid	400	The tenant lifecycle state filter is not Active, Suspended or Archived.
tenants.user.email.invalid	400	The invitation email is not a valid address; checked before the identity server is called.
tenants.user.phone.invalid	400	The invitation phone is not 8–15 digits with an optional leading +; checked before the identity server is called.
tenants.user.identityExists	409	The email or phone already identifies someone in the realm who belongs to a tenant; one identity belongs to one tenant.
tenants.tenant.suspended	409	The tenant is suspended and read-only; every mutating request is refused until it is reactivated.
tenants.tenant.archived	409	The tenant is archived; the state is terminal and blocks all writes.
tenants.user.identityProvisioningFailed	500	Keycloak refused or was unreachable while creating the identity; no user and no invitation were written.
tenants.user.deactivationFailed	500	Keycloak refused or was unreachable while disabling the identity; the user is still active and still signs in.
tenants.user.roleRevocationFailed	500	Keycloak refused or was unreachable while clearing the role attribute; the role is still assigned and still reaches every token the realm issues.
tenants.user.cannotModifySelf	409	A user cannot change their own role, revoke their own role or deactivate themselves; another Administrator has to do it, so a tenant can never lose its last Administrator this way.
tenants.user.roleChange.targetInvalid	400	The requested role is not one a role change can assign; only Administrator and Dispatcher can be switched between.
tenants.user.roleChange.notAllowed	409	This user’s role cannot be changed — the user is a Driver, is deactivated, or has had their role revoked.
tenants.user.roleChangeFailed	500	Keycloak refused or was unreachable while writing the role attribute; the previous role is still assigned and still reaches every token the realm issues.
tenants.profile.invalid	400	A first or last name is empty, longer than 100 characters, or contains control characters.
tenants.profile.updateFailed	500	Keycloak refused or was unreachable while writing the name; nothing was changed.
tenants.user.alreadyInvited	409	This tenant already has a non-deactivated user for the contact; re-invite that user (POST /api/users/{id}/reinvite) instead of inviting again.
tenants.user.reinvite.notPending	409	Only a user whose invitation is still pending (status Invited, with a role) can be re-invited.
tenants.country.required	400	Country is required when provisioning a tenant.
tenants.country.invalid	400	Country must be an ISO 3166-1 alpha-2 code (e.g. AZ).
tenants.fuelPrice.invalid	400	Fuel price per litre must be a non-negative amount.

trips

Код	Статус	Описание
trips.outcomes.lineNotLoaded	400	The line’s goods were recorded as not loaded at the warehouse, so they cannot have been delivered or collected at the customer.
trips.notFound	404	No trip with the given identifier belongs to the current driver.
trips.stop.illegalTransition	409	Illegal stop-status transition.
trips.stop.reasonRequired	400	A reason code is required for this terminal stop status.
trips.stop.notFound	404	No stop at the given index on this trip.
trips.stop.tripNotActive	409	Trip must be Confirmed or InProgress to change a stop status.
trips.stop.planChangedWhileOffline	409	The trip’s stops were renumbered after this offline action was recorded, so its stop index can no longer be trusted.
trips.stop.identityMismatch	409	The stop at this index no longer serves the orders the driver’s action was recorded against — the plan was rearranged; the dispatcher reviews the captured action.
trips.stop.invalidCoordinates	400	GPS coordinates must include both latitude and longitude within valid ranges.
trips.stop.notInProgress	409	Proof of delivery can only be captured while the stop is in progress.
trips.proof.recipientRequired	400	A recipient name is required to capture proof of delivery.
trips.stop.notDeliveryStop	409	Outcomes are not recorded on this stop (Load, warehouse drop).
trips.outcomes.lineMismatch	400	Outcomes must cover exactly the stop’s order lines (one per line, no missing or extra).
trips.outcomes.invariantViolation	400	Per delivered line Delivered+Returned+Lost must equal Requested and Rejected must not exceed Returned; per collected line Collected+NotCollected must equal Requested; all quantities must be non-negative.
trips.outcomes.wrongVocabulary	400	A line mixes the delivery quantities (delivered, returned, rejected, lost) with the collection quantities (collected, notCollected); each line uses the one its stop implies.
trips.outcomes.required	400	A Pickup, customer Return or Rebox stop cannot be closed as PartiallyCompleted by a plain status change; record the partial collection through the outcome door (per-line collected and notCollected quantities).
trips.outcomes.amendReasonRequired	400	An outcome amendment requires a reason.
trips.outcomes.amendLocked	409	A cancelled trip’s outcomes cannot be amended.
trips.outcomes.amendNotTerminal	409	Only a finished stop’s outcomes can be amended.
trips.outcomes.amendReturnReceived	409	The returned or collected goods were already received at the warehouse; reverse that receipt first.
trips.outcomes.amendReturnPending	409	A warehouse return leg already carries these lines’ returned quantity, or a line’s collected quantity has already been raised above zero; adjust or reverse it before amending.
trips.outcomes.reasonRequired	400	A reason code is required for each non-zero returned, rejected, lost, or not-collected quantity.
trips.mutation.etaImpact	409	The change increases the trip ETA; re-submit with acknowledgeEtaImpact=true to proceed.
trips.mutation.tripNotInProgress	409	The trip must be InProgress to insert, skip, or reorder stops.
trips.mutation.invalidPosition	409	The insert position is outside the unvisited region or violates return-stop ordering.
trips.mutation.stopAlreadyStarted	409	The targeted stop has already started and can no longer be skipped or merged into.
trips.mutation.loadStopNotSkippable	409	A loading stop cannot be skipped; slice 2 defines what that means.
trips.mutation.invalidReorder	400	The reorder must be a permutation of the unvisited (pending) stop indices and preserve return-stop ordering.
trips.mutation.tripNotCancelable	409	Only a confirmed or in-progress trip can be cancelled.
trips.mutation.cancelReasonRequired	400	A reason code is required to cancel a trip.

vehicles

Код	Статус	Описание
vehicles.fuelConsumption.invalid	400	Fuel consumption must be positive when provided.
vehicles.compartment.skillUnknown	400	A compartment skill is not in the tenant’s configured capability-skill schema.