Error reference
All non-2xx responses from /api/v1/* use RFC 7807 application/problem+json:
1HTTP/1.1 422 Unprocessable Entity
2Content-Type: application/problem+json
3
4{
5 "type": "https://vorgio.app/problems/validation-failed",
6 "title": "The given data was invalid.",
7 "status": 422,
8 "detail": "The invoice.positions.0.amount_cents field is required when invoice.positions.0.mode is fixed.",
9 "errors": {
10 "invoice.positions.0.amount_cents": [
11 "The amount_cents field is required when mode is fixed."
12 ]
13 }
14}
The type URI is stable and is what your code should branch on — never the title (which is human-readable and may be translated).
#Common problem types
#validation-failed (422)
Body shape error. Includes an errors object keyed by field path.
What to do: surface to the developer / merchant; never to the end customer (the field paths leak schema). Most validation errors mean your shop sent something Vorgio doesn't accept — fix the request shape.
#idempotency-key-conflict (409)
You re-used an Idempotency-Key with a different request body. Vorgio refuses because the only safe behaviour is to surface the conflict.
What to do: pick a different idempotency key (or scope the existing one to this attempt — append a retry counter, e.g. wc-order-1234-checkout-r2). Don't modify the body and re-send under the same key.
#forbidden (403)
The token doesn't have the ability the endpoint requires. For example, calling POST /v1/checkouts with a token that only has clients:read.
What to do: re-issue the token with the correct abilities. The "Payment-provider integration" preset on the token UI selects the right set.
#unauthenticated (401)
Bearer token is missing, malformed, or expired/revoked.
What to do: check the Authorization header. The format is Bearer {numeric_id}|{plain_secret} — both halves separated by a pipe. Don't send only the secret half.
#too-many-requests (429)
Rate limit exceeded. See Rate limits.
#not-found (404)
The resource doesn't exist in your team. Note that resources in other teams also return 404, not 403 — this is intentional (avoids leaking the existence of other teams' data).
What to do: double-check the client_id / invoice_id. If it should exist, check whether it was soft-deleted or whether the token belongs to the wrong team.
#client-has-retained-invoices (409, on DELETE /v1/clients/{id})
You tried to delete a client that has invoices inside the German 10-year legal-retention window (HGB §257, AO §147). Vorgio refuses by law.
What to do: don't delete; archive in your shop instead.
#invoice-not-editable (422, on PATCH /v1/invoices/{id})
You tried to change a finalised invoice, which GoBD forbids, or to set is_draft: true or a different type on a numbered row. This problem has no errors map, because no field is at fault.
What to do: reverse a finalised invoice via POST /v1/invoices/{id}/cancel. Don't retry the PATCH.
#internal-error (5xx)
Something exploded server-side. The detail may contain an error reference for support.
What to do: retry with exponential back-off; if it persists, send the error reference to Vorgio support. Don't show the internal error message to your end customer.
#Validation-error field paths
For nested request bodies (like /v1/checkouts), error keys use dot-notation:
| Path | What it means |
|---|---|
client.external_id |
Top-level field on the client block |
invoice.positions.0.amount_cents |
The amount_cents field on the first position |
send.cc.2 |
The third entry in the send.cc array |
When surfacing errors back to a developer, render each errors array entry as a bullet list under its field path.
#Suggested error-handling pattern (PHP)
1try {
2 $response = $http->post('/api/v1/checkouts', [...]);
3} catch (RequestException $e) {
4 $body = json_decode((string) $e->getResponse()->getBody(), true);
5 $type = $body['type'] ?? '';
6
7 match (true) {
8 str_ends_with($type, 'validation-failed') => $this->reportToDeveloper($body),
9 str_ends_with($type, 'too-many-requests') => $this->scheduleRetry($body, $e->getResponse()->getHeader('Retry-After')[0] ?? 60),
10 str_ends_with($type, 'idempotency-key-conflict') => $this->logAndAlertEng($body),
11 $e->getCode() >= 500 => $this->retryWithBackoff(),
12 default => throw $e,
13 };
14}