---
title: "Errors"
description: "Learn how KOMOJU uses HTTP status codes and JSON error objects to report failures, and explore the full list of error codes you may encounter."
url: "https://docs.priv.staging.komoju-dev.tools/en/docs/introduction/errors"
source_url: "https://docs.priv.staging.komoju-dev.tools/en/docs/introduction/errors.md"
language: en
last_modified: "2026-03-23"
---

KOMOJU uses HTTP status codes to indicate the success or failure of a request. Below are the the following status codes you can expect to see.

| Code | Description |
| --- | --- |
| `200 OK` | The server successfully processed the request |
| `202 Accepted` | The resource is successfully created but the process is not finished |
| `204 No Content` | The server successfully processed the request, but is not returning any content. |
| `401 Not Authorized` | API key provided was invalid or missing |
| `403 Forbidden` | API key provided doesn't have permission to access specified resource |
| `404 Not Found` | Resource not found |
| `422 Unprocessible Entity` | Missing or invalid parameters |
| `500 Internal Server Error` | Something went wrong on our side |
| `502 Bad Gateway` | Upstream payment processor returned an error |
| `503 Service Unavailable` | Server maintenance |

# JSON Error Object

Errors are returned in JSON format. A `code` and `message` parameter are returned for each error message.

## Attributes

| Parameter | Type | Description |
| --- | --- | --- |
| `message` | _string_ | a string describing the error message |
| `code` | _string_ | error code |
| `param` | _string_ | parameter having the validation error |

```json
"error": {
  "message": "A required parameter (amount) is missing",
  "code": "missing_parameter",
  "param": "amount"
}

```

# Error Codes

Here are the possible error codes that will show up in the above `code` field.

| Error Code | HTTP Status | Example Message |
| --- | --- | --- |
| `bad_request` | 400 | The server cannot or will not process the request due to something that is perceived to be a client error |
| `unauthorized` | 401 | User authorization failed |
| `not_found` | 404 | The requested resource could not be found but may be available again in the future |
| `internal_server_error` | 500 | Something went wrong on our side. We're automatically notified of these and try to fix them ASAP |
| `forbidden` | 403 | You are not authorized to perform that action |
| `unprocessable_entity` | 422 | The request was well-formed but was unable to be followed due to semantic errors |
| `bad_gateway` | 502 | We are unable to process your request due to an invalid response from the upstream server |
| `gateway_timeout` | 504 | When attempting to process your payment, we encountered a gateway timeout. Fear not, we have not processed the payment. Please try your payment again |
| `service_unavailable` | 503 | The server is down for maintenance. Please try again later. |
| `request_failed` | 402 | The request failed |
| `invalid_version` | 422 | The specified API version is invalid |
| `invalid_payment_type` | 422 | Payment method was invalid. "credit_card" is not one of "konbini", "paypay" |
| `invalid_token` | 422 | The token you requested is invalid |
| `invalid_currency` | 422 | The currency you requested is invalid |
| `not_refundable` | 422 | The payment you requested is not refundable |
| `not_capturable` | 422 | The payment you requested is not capturable |
| `not_cancellable` | 422 | This payment is noncancellable |
| `fraudulent` | 422 | This payment is fraudulent |
| `invalid_parameter` | 422 | The value of amount is invalid |
| `missing_parameter` | 422 | A required parameter (amount) is missing |
| `insufficient_funds` | 502 | Insufficient funds |
| `used_number` | 502 | Used number |
| `card_declined` | 502 | Card declined |
| `invalid_password` | 502 | Invalid password |
| `bad_verification_value` | 502 | Bad verification value |
| `exceeds_limit` | 502 | Exceeds limit |
| `card_expired` | 502 | Card expired |
| `invalid_number` | 502 | The number you requested is invalid |
| `invalid_account` | 502 | Invalid account |
| `restricted_account` | 502 | Restricted account |
| `other_error` | 502 | Other error |
| `invalid_user_key` | 502 | Invalid user key |
| `other_invalid` | 502 | Invalid card |