Errors

v1 endpoints return a stable error envelope:

{
  "success": false,
  "error": {
    "code": "INVALID_PROVIDER_ORDER_ID",
    "message": "The provider order ID does not match the Opportunity.",
    "field": "provider.provider_order_id",
    "request_id": "req_3f9c2a1b8e7d6c5a4b3d2e1f"
  },
  "request_id": "req_3f9c2a1b8e7d6c5a4b3d2e1f"
}

Common codes

Code	Typical HTTP status	Meaning
`MISSING_API_KEY`	401	`Authorization` header absent
`INVALID_API_KEY`	403	Bearer token not recognised
`PROVIDER_KEY_MISMATCH`	403	Key does not match `provider_code`
`VALIDATION_ERROR`	400	Required/invalid fields
`PROVIDER_NOT_FOUND`	404	Unknown provider configuration
`CHECKOUT_NOT_FOUND`	404	Unknown checkout for this provider
`INVALID_CHECKOUT_TOKEN`	401	JWT invalid or mismatched
`EXPIRED_CHECKOUT_TOKEN`	401	JWT expired
`CONFLICT`	409	Checkout/DDA state conflict
`IDEMPOTENCY_CONFLICT`	409	Idempotency key reused with conflicting state
`METHOD_NOT_ALLOWED`	405	Unsupported HTTP method/route
`INTERNAL_ERROR`	500	Unexpected failure

Validation responses may include:

"details": {
  "missing_fields": ["student.email"],
  "invalid_fields": ["pricing.course_price"]
}

Request IDs

Every response includes request_id and the X-Request-Id header.

Send your own ID with X-Request-Id when correlating provider logs
Otherwise StudentPay generates req_<hex>
Quote this ID in support requests