Error Codes

Melon uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

Codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, authentication failed).
Codes in the 5xx range indicate an error with Melon's servers (these are rare).

Error Response Format

All error responses return a standardized JSON envelope containing success: false and an error object with a specific code and message.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'bvn' field must be exactly 11 digits."
  }
}

Status Code	Name	Description
200	`OK`	Everything worked as expected.
201	`Created`	The resource (e.g., a customer) was successfully created.
400	`Bad Request`	The request was unacceptable, often due to missing a required parameter or invalid data format.
401	`Unauthorized`	No valid API key provided.
403	`Forbidden`	The API key doesn't have permissions to perform the request (e.g., missing scope).
404	`Not Found`	The requested resource doesn't exist.
429	`Too Many Requests`	You hit the rate limit for your API tier.
500, 502, 503, 504	`Server Errors`	Something went wrong on Melon's end.

The error.code string provides a programmatic identifier for the type of error that occurred.

UNAUTHORIZED: Your API key is missing or invalid. Check your Authorization header.
FORBIDDEN: Your API key lacks the required scope (e.g., trying to write with a kyc:read key).
VALIDATION_ERROR: One or more fields in your request body were invalid. The message will provide specific details.
RESOURCE_NOT_FOUND: The requested ID (e.g., customerId) does not exist in your organization.
DUPLICATE_RESOURCE: A resource with the provided unique identifier (like an email or phone number) already exists.
RATE_LIMIT_EXCEEDED: You have exceeded the allotted API requests for your current plan. See the Rate Limits guide.