Guides
/
Error Handling

Error Handling

API error responses and how to handle them

All Vivamo API errors follow a consistent JSON format.

Error response format

Error responses always include a message field. Some errors include additional fields depending on the context:
FieldTypeAlways presentDescription
message
string
Yes
A human-readable description of the error.
errors
array
No
Detailed validation errors. Present when request body, query, or path parameters fail validation.

HTTP status codes

StatusMeaningWhen it occurs
200
Success
The request was processed successfully.
400
Bad Request
The request was invalid — missing fields, failed validation, duplicate records, expired intents, or business logic violations. This is the most common error status.
403
Forbidden
The API key is invalid, the client secret has expired, or the customer's location is blocked by geolocation rules.
500
Internal Server Error
An unexpected server-side error occurred. These are rare and should be retried.

Almost all application-level errors return 400. Authorization failures (invalid API key, expired client secret) return 403 via the API Gateway.

Validation errors

When a request body, query parameter, or path parameter fails validation, the response includes an errors array with specific constraint details:

Each entry in the errors array is an object where the key is the validation constraint name and the value is a description.

Common errors by endpoint

Customer creation

MessageCause
This customer already exists
A customer with the same externalCustomerId is already linked to your operator.
A customer with this email address already exists.
The email is already in use by another customer.
Sorry, this email domain is not supported
The email uses a disposable email provider.
Sorry, this phone number cannot be used. Please use a valid mobile number.
The phone number is not a valid mobile number (landlines and VOIP numbers are rejected).

Payment intents

MessageCause
Customer with provided externalId not found.
No customer exists with the given externalCustomerId.
Both externalCustomerId and newCustomer cannot be provided at the same time.
The request includes both an existing customer reference and new customer data.
Either externalCustomerId or newCustomer must be provided.
Neither field was included in the request.

Disbursement intents

MessageCause
Customer with provided externalId not found.
No customer exists with the given externalCustomerId.

Authorization errors

When an API request fails authentication (invalid or missing API key, expired client secret), the response comes from the API Gateway rather than the application:

This occurs when:

  • The Authorization header is missing or malformed
  • The secret key or client secret key is invalid
  • The client secret key has expired
  • The operator account is disabled
  • The customer's location is blocked by geolocation rules

Best practices

  • Check the HTTP status code first. A 200 means success; anything else means the request did not complete as expected.
  • Parse the message field for logging or display to internal users.
  • Handle errors arrays for validation failures by mapping them to specific form fields during development.
  • Retry on 500 errors with exponential backoff. These indicate transient server issues.
Built with