Errors

Every error uses the same format.

{
  "error": {
    "type": "invalid_request_error",
    "code": "branch_not_connected",
    "message": "Branch 'noerrebro' has no active connection to a fleet zone.",
    "param": "branch",
    "doc_url": "https://docs.univooz.com/errors/branch_not_connected",
    "request_id": "req_01KZCCF8ZH4M7XQ2VB9RSTNPKD"
  }
}

Field	Meaning
`type`	The group. Five values, and they never change.
`code`	The exact error. A code never changes its meaning. Use this in your code.
`message`	Text for a person. It can change at any time. Never use it in your code.
`param`	The field that caused the error, if one field caused it.
`doc_url`	The page for this code.
`request_id`	Give this to support.

The five types

Type	Meaning	Your action
`invalid_request_error`	Your request is not correct.	Correct the request.
`authentication_error`	Your key is missing, unknown, revoked or expired.	Correct the key. Do not try again.
`billing_error`	Your plan or your payment.	Upgrade, or pay the invoice.
`rate_limit_error`	Too many requests.	Wait, then try again.
`api_error`	A failure in Univooz.	Try again, with increasing delays.

400 or 422

400 — Univooz could not read the request. Your code is wrong.
422 — Univooz read the request, and a rule rejected it. Your data is wrong.

invalid_request is 400 only.

Field errors

A validation failure adds a details list, so you can correct everything one time:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "The request contains 2 invalid fields.",
    "request_id": "req_01KZCCF8ZH4M7XQ2VB9RSTNPKD",
    "details": [
      { "code": "invalid_value", "message": "Not a valid phone number.", "param": "customer.phone" },
      { "code": "required", "message": "This field is required.", "param": "schedule.mode" }
    ]
  }
}

details[].code has three values only:

Code	Meaning
`required`	The field is necessary and is missing.
`invalid_value`	The value is not acceptable.
`unknown_field`	This request has no such field.

One field can give more than one entry, one for each failed rule. Show details as a list. Do not use param as a unique key.

request_id

Every response has request_id, in the body and in the Request-Id header. Give it to support.

The value is req_ and then a ULID. Treat it as text. The length and the characters can change.

request_id belongs to the response, not to an order. It is absent from data[] in a list, and from data in a webhook.

All 30 codes

Authentication

Code	Status	Cause
`invalid_api_key`	401	Missing, incorrect or unknown
`api_key_revoked`	401	Somebody revoked it
`api_key_expired`	401	It passed its expiry date
`test_mode_required`	403	A test endpoint with a live key

Plan and payment

Code	Status	Cause
`subscription_inactive`	402	The subscription is unpaid or cancelled
`feature_not_available`	403	The endpoint needs an Advanced plan

Destination

Code	Status	Cause
`branch_required`	422	No `branch`, and you have more than one active branch
`branch_not_found`	422	No branch has that reference or id
`branch_not_connected`	422	The branch has no primary connection
`branch_address_missing`	422	The branch has no usable main address
`zone_not_connected`	422	The branch has no connection to that zone

Addresses

Code	Status	Cause
`address_not_found`	422	The result was no better than the country
`address_ambiguous`	422	More than one result
`address_low_confidence`	422	A real place, but not accurate

Times

Code	Status	Cause
`pickup_time_in_past`	422	The time passed
`delivery_before_pickup`	422	The times are in the wrong sequence
`pickup_buffer_violation`	422	Too soon for the minimum notice
`no_shift_coverage`	422	No shift covers the pickup

Orders

Code	Status	Cause
`duplicate_external_order_id`	409	That id is in use, in one of the two modes
`order_not_found`	404	Unknown, or in the other mode, or another organization
`order_not_cancellable`	422	Too late to cancel, or the order is complete
`order_not_amendable`	422	The courier has the goods
`field_not_amendable`	422	That field controls routing or identity
`invalid_status_transition`	422	Not possible from this status

General

Code	Status	Type
`invalid_request`	400	`invalid_request_error`
`unknown_endpoint`	404	`invalid_request_error`
`request_too_large`	413	`invalid_request_error`
`invalid_time_range`	422	`invalid_request_error`
`rate_limit_exceeded`	429	`rate_limit_error`
`internal_error`	500	`api_error`

On this page