Resources

Error Codes

Overview

Otonum uses standard HTTP status codes and a consistent error response body. Always check the status code and parse the error payload to handle failures correctly.

Error Response Format

Code
{
  "error": "ERROR_CODE",
  "errorMessage": {
    "fr": "French description.",
    "en": "English description."
  }
}

HTTP Status Codes

Status	Meaning	When it occurs	Action
200	OK	Request succeeded	Process the response
400	Bad Request	Malformed JSON or missing required field	Fix the request payload
401	Unauthorized	Missing or invalid API key	Verify x-api-secret header
403	Forbidden	Key is valid but has insufficient permissions or sandbox limits	Verify environment and operation
404	Not Found	Member, voucher, or resource was not found	Verify identifier
409	Conflict	Duplicate reference	Do not resubmit. Activity is already registered
422	Unprocessable Entity	Semantic validation failed for request body	Read error details for the specific field
429	Too Many Requests	Rate limit exceeded (10 req/s per API key)	Retry with exponential backoff
500	Internal Server Error	Unexpected server error	Retry once; contact support if persistent

Error Codes

Authentication

Code	Description
UNAUTHORIZED	Missing or invalid API key
FORBIDDEN	API key does not have access to this resource

Member

Code	Description
CUSTOMER_NOT_FOUND	No member found with provided personal code or email
CUSTOMER_ALREADY_EXISTS	A member with this email or phone is already enrolled
CONSENT_REQUIRED	Enrollment request is missing consent information
INVALID_POLICY_VERSION	Provided consent policy version does not match the current required version

Transactions and Activities

Code	Description
DUPLICATE_REFERENCE	An activity with this reference already exists
VOUCHER_NOT_FOUND	redemptionCode does not match an active voucher
VOUCHER_ALREADY_CONSUMED	Referenced voucher was already used
VOUCHER_EXPIRED	Referenced voucher has expired
VOUCHER_NOT_RESERVED	Attempt to redeem voucher without prior reservation

Vouchers

Code	Description
INSUFFICIENT_BALANCE	Member balance is below minimum redemption threshold
VOUCHER_CREATION_DISABLED	Voucher creation is not available in this environment (sandbox)

Rate Limiting

Code	Description
RATE_LIMIT_EXCEEDED	Limit of 10 requests/second per API key is reached

Key Points

• A 409 Conflict on purchase does not mean purchase failed. It means purchase was already processed successfully. Do not resubmit.
• In sandbox environment, voucher operations can return 403 by design. See Authentication for sandbox details.

See Also

• Best Practices
• Authentication