Errors

Every error the API returns, what causes it, and how to fix it.

Errors

Every error response carries the same envelope, and every error links back to its section on this page via docsUrl — a pasted error is enough to find the fix.

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key",
    "requestId": "req_msh2k1x9_a8b2c3d4",
    "docsUrl": "https://vortex.nyc/payments/docs/guides/errors#unauthorized"
  }
}

Keep the requestId when reporting a problem — it is the correlation key for the exact request on our side.

bad-request

The request was malformed before validation began — unparseable JSON, a missing body, or a structurally wrong payload. Check the request against the operation’s schema in the API reference; every reference page carries a working sample.

unauthorized

The API key is missing, invalid, revoked, expired — or valid for the other environment. Keys carry their environment: vp_test_ keys only reach sandbox data, vp_live_ keys only production, and a request whose stated environment disagrees with the key’s is refused. If a key that worked stopped working, check revocation and expiry before anything else. See Authentication and Sandbox & environments.

forbidden

The key is valid but not allowed to do this — most commonly a merchant-scoped key calling an operator surface, or acting on a merchant account owned by a different organization.

not-found

The resource id does not exist in this environment and organization. The classic miss: created in sandbox, queried with a live key (or the reverse). Ids are environment-scoped.

conflict

The request is well-formed but the current state disallows it — collecting a voided invoice, funding a settlement that is not fundable, re-using state that has moved on. The message names the specific state; resolve the state, don’t retry the request unchanged.

rate-limited

The key exceeded its rate limit. Limits apply per key in both environments so sandbox load behavior is representative. Back off and retry; the SDK’s auto-retry treats this as retryable.

validation-failure

The body parsed but a field is wrong — the envelope’s details.fieldErrors maps each offending field to its reasons. Amounts are integer minor units (cents); floats are the most common cause.

not-implemented

The route exists but the capability is not available for this account or environment. The message says which capability; some (like on-demand payouts) require enablement on your account.

internal-error

Our fault, not yours. The requestId is the handle — send it to us. If it recurs, check the status of the platform before retrying aggressively.