Documentation
Integration setup ↗

Error codes

Videpay returns standard HTTP status codes wrapped in a consistent JSON envelope. Most integration issues are authentication, validation, or business-rule errors, all surfaced in the `message` field. Read `message` first. It's giving stack trace, but polite.

Need machine-readable request/response bodies for your AI or codebase? Download this page as plain Markdown.

When should I use this?

  • Your API call returned 4xx or 5xx and you need to fix it.
  • You are building error handling in your integration.

Why use Videpay?

  • Consistent error shape across all endpoints.
  • Actionable messages, not opaque error codes.

Debugging 401 on sandbox

Your script gets 401 Unauthorized. You check: using sandbox API key? Calling sandbox.api.videpay.io? x-api-key header set? Fixing the env var resolves it. Classic environment mismatch: we've all been there, no judgment.

Common errors

  1. 400 Bad Request: invalid body, failed validation, or business rule rejected (e.g. unsupported token, insufficient balance).
  2. 401 Unauthorized: missing/invalid API key or session.
  3. 403 Forbidden: authenticated but not allowed for this business or action.
  4. 404 Not Found: unknown ID or resource outside your business scope.
  5. 409 Conflict: duplicate reference, invalid state transition, or concurrent update conflict.
  6. 429 Too Many Requests: rate limited. Back off and retry. The API said 'please chill' in HTTP.
  7. 500 Internal Server Error: transient server issue. Retry with the same idempotency key when applicable.

Error response shape

Every failed API call returns the same JSON envelope from the global exception handler, not the raw NestJS `{ error: "Bad Request" }` object alone. Read `message` first; use `details` for any extra fields Nest attached (usually `{ error: "Bad Request" }`). Validation errors are a single `message` string (multiple field issues joined with `; `).

What to log vs show users

Log `statusCode`, `path`, and `message` for debugging. `url`, `ip`, and `health` are diagnostic metadata: do not surface them to end users.

FieldTypeRequiredDescription
statusCodeintegerYesHTTP status (same as response status line).
messagestringYesHuman-readable error. Validation failures look like `amount: amount must be a valid positive number string`.
detailsobjectNoOptional extra context. Often `{ error: "Bad Request" }` or `{ error: "Unauthorized" }`.
methodstringNoHTTP method of the failed request.
pathstringNoRequest path without query string.
timestampstringNoISO-8601 time the error was generated.
environmentstringNoServer environment (e.g. sandbox, live).
POST(any endpoint)

Typical validation error (400).

POST(any endpoint)

Missing or invalid API key (401).

← Supported chainsChangelog →