Stream API Errors

This page documents the error response format and the standardized error codes returned by Stream API endpoints. The goal is to provide a stable, predictable contract for client applications and integrators.

Error response envelope

All handled errors return a response body in this format:

{
  "error": {
    "code": "STREAM_ERROR",
    "message": "Something wrong happened, please contact support.",
    "additional_info": "Optional human-readable details"
  }
}

• code: A stable error code from StreamErrorCodes.
• message: A user‑facing message associated with the code.
• additional_info: Optional, best‑effort details to aid debugging.

HTTP status codes

HTTP status	Meaning
400	The request is invalid.
401	The API key is missing or invalid.
403	The API key doesn't have permission for this action or resource.
404	The resource doesn't exist.
410	The resource is no longer available.
422	The request failed validation, or a value conflicts with an existing record.

Stream error codes

The following codes are used across all Stream API endpoints:

Code	Message
STREAM_ERROR	Something wrong happened, please contact support.
STREAM_UNKNOWN_ERROR	Unknown exception happened; this exception will be handled as soon as possible.
PHONE_ALREADY_REGISTERED	Phone is already registered.
INVALID_PARAMETERS	Request input is not valid.
INVOICE_FINALISED	Invoice is finalised and cannot undergo this action.
PAYMENT_REFUNDED_ALREADY	Duplicate action; payment has already been refunded.
PAYMENT_REFUNDED_FAILED	Could not refund payment; processor failed.
DUPLICATE_CONSUMER	Consumer already exists.
DUPLICATE_PAYMENT	A payment with the given information already exists.
PERMISSION_FORBIDDEN	Permission forbidden.
PRODUCT_USED_IN_FINALIZED_INVOICE	Product cannot be updated; it is used by a finalized invoice.
COUPON_USED_IN_FINALIZED_INVOICE	Coupon cannot be updated; it is used by a finalized invoice.