Skip to main content
Safepay Raast returns structured errors that include an error code and message. Some endpoints wrap the error in an api_version envelope, while others return the error fields at the top level.

​
Error response formats

​
Envelope format

Some responses include api_version and an error object. 
{
  "api_version": "v1",
  "error": {
    "code": "error.unauthorized_access",
    "message": "partner access key is required in request header"
  }
}

​
Flat format

Other responses return code and message at the top level. 
{
  "code": "error.bad_request",
  "message": "Invalid request parameters"
}
Check the API reference for the exact error shape per endpoint.

​
Common status codes

StatusMeaningTypical action
400Bad requestValidate request payloads and required fields.
401UnauthorizedConfirm X-SFPY-AGGREGATOR-SECRET-KEY and environment.
404Not foundVerify the resource ID exists and belongs to your aggregator.
409ConflictRetry with a new idempotency key or resolve duplicate creation.
500Internal errorRetry with backoff and contact support if persistent.

​
Handling errors safely

  • Use request_id for idempotent create calls and reuse it only when retrying the same payload.
  • Log code, message, and the HTTP status for support escalations.
  • Prefer webhooks as the source of truth for asynchronous workflows.

​
Example: unauthorized error

curl --request GET "{{base_url}}/v1/aggregators/{{aggregator_id}}" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: invalid"

​
See also