Errors

{
  "code": "insufficient_balance",
  "error": "Not enough funds",
  "request_id": "9f3c1e2a7b4d5e60"
}

Branch on code. Some errors carry extra fields:

{
  "code": "invalid_targeting",
  "error": "Unknown city",
  "field": "city",
  "value": "nosuchcity"
}
{
  "code": "unsupported_field",
  "error": "Field is not supported here",
  "field": "count"
}
{
  "code": "rate_limited",
  "error": "Too many requests",
  "retry_after": 12,
  "limit": 120
}

A 404 on GET /api/v1/orders/{id} carries only error and request_id, without code.

Code catalog

Code	Status	When
`invalid_api_key`	401	the key was not accepted
`validation_failed`	400	a field constraint is violated
`invalid_body`	400	the body or a field has the wrong shape
`unknown_product`	400	unknown slug or the product is not on sale
`insufficient_scope`	403	the key lacks the scope the route requires
`not_found`	404	the resource does not exist or belongs to another account
`idempotency_in_progress`	409	the previous request with this key is still running
`replace_in_progress`	409	a replacement of the package addresses is already running
`invalid_volume`	422	the volume is outside the product’s range
`invalid_quantity`	422	more addresses than one purchase can take
`country_unavailable`	422	the country is not sold for this product
`unknown_plan`, `unknown_operator`, `unknown_period`	422	the selected country has no such plan, location or period - check the options
`out_of_stock`	422	the location has fewer free addresses than requested
`unsupported_capability`	422	the operation does not apply to this package’s kind
`package_expired`	422	the address package term has ended - extend first
`prolong_window_closed`	422	the addresses can no longer be brought back by a renewal - a new purchase is needed
`type_unavailable`	422	the configuration can be neither quoted nor sold
`insufficient_balance`	422	not enough funds
`unsupported_field`	422	the body has an inapplicable key; comes with `field`
`invalid_targeting`	422	the value is not in the geo catalog; comes with `field` and `value`
`package_unavailable`	422	the operation is not possible in the package’s current state or with these settings
`purchase_refunded`	422	the purchase did not go through, the money was returned
`idempotency_key_required`	422	no `Idempotency-Key` header
`idempotency_key_invalid`	422	the header is empty or longer than 255 characters
`idempotency_key_reused`	422	the same key with a different body
`rate_limited`	429	the key’s budget is used up
`replace_cooldown`	429	the addresses were replaced recently; when you can do it again - in `replace_available_at`
`order_failed`	500	the order was not placed, the balance was not charged
`package_failed`	500	the package operation failed, money was not charged
`order_needs_attention`	500	money charged, issuance did not happen, handled manually
`operation_indeterminate`	500	a retry with the key of an operation whose outcome is undetermined
`catalog_unavailable`	503	the product’s geo catalog is not synchronized yet

Paid operations

Code	Money	Action
`order_failed`, `package_failed`	not charged	retry with the same `Idempotency-Key`
`purchase_refunded` (422)	returned	retry as a new purchase with a new key
`order_needs_attention`	charged, outcome being investigated	do not retry, contact support with `order_id`
`operation_indeterminate`	outcome undetermined	do not retry with the same key; check orders and packages, then contact support

The message in a 5xx is neutral - branch on code.

Support: @ipvrent_support, [email protected]. Include the request_id from the error body and the order_id, if there is one.

Retries

A timeout is not a failure: the request may have arrived. A retry with the same Idempotency-Key returns the same response. On 409 idempotency_in_progress wait and retry with the same key.

Do not retry: insufficient_balance, invalid_volume, invalid_quantity, unknown_product, unsupported_field, unsupported_capability, invalid_targeting, prolong_window_closed. On rate_limited wait for Retry-After, on replace_cooldown - for replace_available_at.