Error Handling

4pay.cc uses standard HTTP status codes and returns structured JSON error bodies.

---

HTTP Status Codes

Code	Meaning
200 OK	Request succeeded
201 Created	Resource created (async — check status via GET)
204 No Content	Operation accepted (no response body)
400 Bad Request	Malformed request
401 Unauthorized	Missing or invalid API key
403 Forbidden	Valid key but insufficient permissions
404 Not Found	Resource does not exist
422 Unprocessable Entity	Validation error (see body)
500 Internal Server Error	Server-side error

---

Validation Errors (422)

When a request fails validation, the API returns a 422 with details about each invalid field:

{
  "detail": [
    {
      "loc": ["body", "cardType"],
      "msg": "value is not a valid enumeration member; permitted: 'virtual', 'physical'",
      "type": "type_error.enum",
      "input": "prepaid",
      "ctx": {}
    }
  ]
}

Field	Description
loc	Location of the error: ["body", "fieldName"] or ["query", "param"]
msg	Human-readable error message
type	Machine-readable error type
input	The value you sent

---

Common Errors

Missing required field

{
  "detail": [
    {
      "loc": ["body", "cardOwnerId"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Invalid UUID

{
  "detail": [
    {
      "loc": ["path", "wallet_id"],
      "msg": "value is not a valid uuid",
      "type": "type_error.uuid"
    }
  ]
}

---

Async Operation Failures

For async operations (card issuance, etc.), a successful 201 does not guarantee the operation completed. Always poll the resource:

# 1. Issue card — returns 201 immediately
POST /api/v2/organizations/{org_id}/wallets/{wallet_id}/instruments

# 2. Poll status
GET /api/v2/organizations/{org_id}/wallets/{wallet_id}/instruments/{instrument_id}

# 3. Check card.status
# "creating"         → still in progress
# "active"           → success
# "creating_failed"  → failed, retry or contact support