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 using the StreamBaseResponse envelope:

{
  "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.

Common error classes and HTTP status codes

The following exception classes map to consistent HTTP status codes:

Exception class	HTTP status
BadRequestError	400
UnauthorizedError	401
ForbiddenError	403
PermissionForbiddenError	403
NotFoundError	404
GoneError	410
UnprocessableEntityError	422
DuplicateValueError	422

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.