Errors
Errors are RFC 9457 problem details (application/problem+json) with a stable code:
{
"type": "https://vestoris.com/developers/errors#insufficient_scope",
"title": "The token lacks a scope",
"status": 403,
"detail": "This call needs the scope \"orders:write\".",
"code": "insufficient_scope",
"instance": "/api/v1/orders",
"required_scope": "orders:write"
}Decide on code, not on detail (the wording may improve). Some problems add fields: errors (per field), hint (what to do), checks (the compliance results of a blocked order), feed_codes (the codes of the Data Feed Reference, such as F008 or V104), etag (the current ETag on 412).
| Code | Status | Meaning |
|---|---|---|
invalid_request | 400 | Invalid request |
https_required | 400 | HTTPS required |
invalid_json | 400 | The body is not valid JSON |
invalid_token | 401 | Invalid or missing token |
session_not_accepted | 401 | Session cookies are not accepted on the API |
insufficient_scope | 403 | The token lacks a scope |
forbidden | 403 | Not allowed |
ip_not_allowed | 403 | This address may not use the client |
user_token_required | 403 | A person must do this |
approvals_not_granted | 403 | This service account may not approve |
legacy_keys_disabled | 403 | Legacy API keys are turned off for this firm |
legacy_key_scope | 403 | Legacy API keys only reach the data, feed and bundle endpoints |
not_found | 404 | Not found |
method_not_allowed | 405 | Method not allowed |
conflict | 409 | Conflict |
invalid_transition | 409 | Not possible in the current state |
idempotency_in_progress | 409 | A request with this Idempotency-Key is still running |
precondition_failed | 412 | The resource changed (ETag) |
payload_too_large | 413 | The file is too large |
unsupported_media_type | 415 | Unsupported media type |
validation_failed | 422 | Validation failed |
compliance_blocked | 422 | Blocked by compliance |
idempotency_key_reused | 422 | Idempotency-Key reused for a different request |
confirmation_required | 428 | Confirmation required |
precondition_required | 428 | If-Match required |
idempotency_key_required | 428 | Idempotency-Key required |
rate_limited | 429 | Too many requests |
server_error | 500 | Server error |
Error answers never contain a token, a secret or another firm's data. Every answer has an X-Request-Id; quote it if you contact us.
The 1.2 data endpoints
POST /api/v1/data/{data set}, POST /api/v1/feeds/{id}/files, POST /api/v1/feeds/bundles and the batch and folder status endpoints keep their 1.2 answers ({"ok": true, "batch": {...}}), and their problems also carry "ok": false and "error", so existing integrations keep working.