Look up operation by idempotency key

Retrieve or reconcile a SafeHaven write in this project environment. Requires events:read and the read scope for the original service. A returned resource can still be pending or failed.

Use with AI

Download Claude instructions Download Codex instructions All AI integration resources

Markdown

GEThttps://api.veyqo.org/api/v1/safehaven/operationsIntegration guide

Use your sandbox environment to start. Understand error codes and payment statuses before handling a live payment.

Look up operation by idempotency key

curl --request GET "https://api.veyqo.org/api/v1/safehaven/operations?idempotency_key=persisted-operation-key" \
  --header "Authorization: Bearer $VEYQO_SECRET_KEY" \
  --header "Accept: application/json"

{
  "success": true,
  "data": {
    "id": "pso_01M6EB66SC61Q3RQYAN0693DGM",
    "operation": "transfer",
    "status": "unknown",
    "resource": null,
    "provider_reference": "pso_01M6EB66SC61Q3RQYAN0693DGM",
    "created_at": "2026-11-02T12:00:00Z"
  }
}

Illustrative examples. Replace IDs and environment variables with your own values. Keep secret keys on your server.

Headers

Authorizationstringrequired: Bearer <secret-key>. This key determines your project environment and must stay on your server.
Acceptstringoptional: application/json

Endpoint

GET https://api.veyqo.org/api/v1/safehaven/operations

Server secret key required. Scope: events:read. The key determines the project and environment; no project-selection header is accepted.

Path and query parameters

Parameter	Location	Required	Description
idempotency_key	query	Yes	The persisted Idempotency-Key used for the write.

Response fields

idstringrequired: Veyqo pso_ operation ID. Also used as the globally unique upstream reference where supported.
operationstringrequired: See the JSON example.
statusstringrequired: Operation execution status, not proof of settled funds. succeeded means a response was received; inspect resource.status. Values: pending, succeeded, unknown, failed.
resourceobject | array | nullrequired: Encrypted-at-rest result, returned only to this environment with the original service read permission.
provider_referencestringrequired: See the JSON example.
created_atstringrequired: Format: date-time.

Errors and recovery

Code	HTTP	Recovery	Retry policy
VALIDATION_FAILED	422	Read error.details when present, correct the named fields and retry only after correction. Validation messages may describe state/capability errors without field details.	No automatic retry.
INVALID_API_KEY	401	Use a current kc_test_ or kc_live_ secret key on /api/v1. Use a pk_test_ or pk_live_ publishable key only on browser checkout.	After fixing credentials.
INSUFFICIENT_PERMISSION	403	Grant the required scope or use a suitably scoped key. Dashboard organization roles and staff permissions are separate.	After permission changes.
RESOURCE_NOT_FOUND	404	Check the ID, project and environment. Do not guess another project’s IDs. An inactive payment link is also not-found.	No blind retry.
PROVIDER_UNAVAILABLE	503	Check the existing payment and verify its state before starting another attempt. Retry safe reads with backoff; preserve operation identity for retried writes.	Conditional: reconcile unknown outcomes first.
PROVIDER_REQUEST_FAILED	422	Read the safe message, inspect the payment’s failure details and correct the request or provider account. Never repeatedly retry a business rejection.	Only after resolving the cause.

Complete error catalogue

Every Veyqo error code, including which surface emits it and how to recover.