Errors

Understand error formats, status codes, and recovery strategies.

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

Status	Meaning	Typical action
400	Bad request	Validate request payloads and required fields.
401	Unauthorized	Confirm X-SFPY-AGGREGATOR-SECRET-KEY and environment.
404	Not found	Verify the resource ID exists and belongs to your aggregator.
409	Conflict	Retry with a new idempotency key or resolve duplicate creation.
500	Internal error	Retry 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

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

See also

• First API call
• Manage aggregator secret keys
• Webhooks delivery
• API reference