Errors & Status Codes - Paymish Developer Documentation

Error Format

{
  "status": false,
  "message": "Invalid API key provided.",
  "error": "INVALID_API_KEY",
  "data": null
}

HTTP Status Codes

200

OK

Request succeeded and the resulting payload is in data.

201

Created

A resource was created successfully.

400

Bad Request

The request is malformed or required fields are missing.

401

Unauthorized

Your API key is missing, invalid, or revoked.

403

Forbidden

Your key is authenticated but does not have permission for the action.

404

Not Found

The requested resource does not exist.

422

Unprocessable Entity

Validation passed syntactically but failed business rules.

429

Too Many Requests

You hit a rate limit. Use the Retry-After header to back off.

500

Server Error

Something failed on our end. Contact support if it persists.

Error Codes

The error field is stable and machine-readable, which makes it a safer signal for conditional logic than the message text.

INVALID_API_KEY

The API key provided is missing, malformed, or revoked.

INSUFFICIENT_FUNDS

The wallet does not have enough balance for this transaction.

DUPLICATE_REFERENCE

A transaction with the supplied reference already exists.

RATE_LIMIT_EXCEEDED

Too many requests were made in a short period.

USER_NOT_FOUND

No user matches the supplied identifier.

Handling Errors

Always branch on both the HTTP status code and the machine-readable error field when deciding whether to retry, prompt for action, or fail permanently.

import requests

response = requests.post(url, headers=headers, json=payload)
data = response.json()

if not data.get("status"):
    error_code = data.get("error")
    message = data.get("message")

    if response.status_code == 401:
        raise Exception(f"Auth failed: {message}")
    elif response.status_code == 429:
        retry_after = response.headers.get("Retry-After", 60)
        print(f"Rate limited. Retry after {retry_after}s")
    else:
        raise Exception(f"API error [{error_code}]: {message}")

try {
  const response = await axios.post(url, payload, { headers });
  const { data } = response;

  if (!data.status) {
    throw new Error(`API error [${data.error}]: ${data.message}`);
  }

  return data.data;
} catch (err) {
  if (err.response?.status === 429) {
    const retryAfter = err.response.headers["retry-after"] || 60;
    console.log(`Rate limited. Retry after ${retryAfter}s`);
  } else if (err.response?.status === 401) {
    console.error("Invalid API key");
  } else {
    throw err;
  }
}

Handle Paymish API failures with consistent status and error codes