Errors

One error envelope, stable codes, clear retry rules.

Every non-2xx response has one shape. Branch on error.code, never on message.

JSON

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid.",
    "request_id": "req_8fK2Lq9ZtX4mN7bV1cW3yH6p",
    "details": [
      {
        "path": "items[3].length",
        "code": "out_of_range",
        "message": "length must be greater than 0."
      }
    ]
  }
}

Field	Holds
`code`	Stable, snake_case
`message`	English, for logs
`request_id`	Also in `X-Request-Id`. Quote it to support
`details[]`	On 400/422: `path`, `code`, `message` per problem

Codes

Status	Code	Meaning	What to do	Retry
400	`invalid_json`	The body is not valid JSON or a field has the wrong type.	Fix the request body.	No
401	`unauthorized`	Missing, malformed or unknown API key.	Send Authorization: Bearer cd_live_…; check the key was copied completely.	No
401	`key_revoked`	The key was revoked.	Create a new key in the developer console.	No
401	`key_expired`	The key passed its expiry date.	Create a new key in the developer console.	No
402	`insufficient_credits`	Available credits do not cover the smallest possible run of this job.	Buy a credit pack or wait for the monthly credits; nothing was charged.	No
403	`ip_not_allowed`	The calling IP is not on the key's allowlist.	Call from an allowed IP or edit the allowlist.	No
403	`subscription_inactive`	The organization has no active subscription that includes the API.	Renew the subscription.	No
403	`account_inactive`	The organization is suspended, or has no owner whose account is active.	Contact support.	No
403	`scope_missing`	The key lacks a scope this endpoint needs.	Use a key with the scope (pack:write, jobs:read, account:read, resources:read, resources:write).	No
403	`preset_read_only`	Presets cannot be changed or deleted.	Create your own vehicle with POST /v1/vehicles.	No
403	`plan_limit_reached`	The organization's plan allows no more projects or cargo items.	Delete projects you no longer need, or move to a larger plan.	No
404	`not_found`	No /v1 endpoint has this method and path.	Check the method and path against the endpoint list.	No
404	`job_not_found`	No job with this id in your organization.	Check the id.	No
404	`vehicle_not_found`	No vehicle with this id among the presets or your organization's vehicles.	Check the id against GET /v1/vehicles.	No
404	`template_not_found`	No template with this id in your organization.	Check the id against GET /v1/templates.	No
404	`project_not_found`	No project with this id in your organization.	Check the id against GET /v1/projects.	No
409	`job_not_finished`	The job is still queued or running.	Poll GET /v1/jobs/{id} until `status` is `succeeded`.	Yes
409	`project_busy`	The project is being packed right now (in the app or by another job).	Wait for that run to end, then retry.	Yes
409	`job_failed`	The job failed; it has no result.	Read `job.error`; failures on our side are not charged (time_limit_exceeded is charged like a canceled job) — resubmit if the cause was temporary.	No
409	`job_canceled`	The job was canceled; it has no result.	Resubmit if needed.	No
409	`job_already_finished`	The job already ended and cannot be canceled.	Nothing to do.	No
400	`idempotency_key_invalid`	The Idempotency-Key header is longer than 128 characters.	Use a shorter key (a UUID works).	No
410	`result_expired`	The result passed the retention window and was deleted.	Resubmit the job if you need the plan again.	No
413	`payload_too_large`	The request body exceeds 10 MB.	Send fewer or simpler items.	No
422	`validation_failed`	The request is well-formed JSON but describes an invalid job. details[] lists every problem.	Fix each details[].path; validation failures are free.	No
429	`rate_limited`	Too many requests in the current minute, hour or day (per key or per organization), or more than 60 failed authentications per minute from your IP address.	Wait Retry-After seconds, then retry with backoff.	Yes
429	`too_many_jobs`	The organization already has the maximum number of queued + running jobs.	Wait for running jobs to finish, then retry.	Yes
500	`internal_error`	Something failed on our side.	Retry with backoff; quote request_id if it persists.	Yes
503	`api_disabled`	The API is temporarily disabled (maintenance) or switched off for the organization.	Retry later.	Yes

Validation details

details[].code on 422 validation_failed:

Code	Meaning
`required`	A required field is missing
`invalid_value`	Wrong type or not one of the allowed values
`out_of_range`	Too small, too large or too long
`duplicate_id`	An id is used twice
`unknown_vehicle`	No preset or vehicle of yours with this `vehicle_id`
`unknown_template`	No template of yours with this `template_id`
`type_not_allowed`	Vehicle type not enabled for your organization
`unknown_group`	An item names a group that is not listed
`does_not_fit`	The item fits no listed vehicle
`too_many_items`	More item units than the job limit
`too_many_vehicles`	More vehicles than the job limit
`unknown_field`	A field the API does not know

Job errors

A failed or canceled job says why in job.error.code:

Code	Meaning
`canceled`	Canceled by DELETE /v1/jobs/{id}. Charged base + compute used.
`time_limit_exceeded`	The compute budget ran out before any vehicle was packed. Charged like a canceled job: per-job fee, large-load surcharge and the compute used, never the per-vehicle fee.
`engine_failed`	The packing engine failed. Not charged.
`queue_timeout`	The job waited too long for a compute slot. Not charged.
`server_restarted`	The service restarted while the job was queued or running. Not charged.

Retries

Retry 429, 500 and 503 with exponential backoff, honouring Retry-After. Send the same Idempotency-Key (Idempotency). Never retry other 4xx unchanged.

Rate limits & limitsRequest rates, job size, concurrency and retention.IdempotencyRetry POST /v1/pack without creating a second job.

Codes#

Validation details#

Job errors#

Retries#

Related#

Codes

Validation details

Job errors

Retries

Related