Skip to main content

API Errors

This guide is only for response errors in our API.

The Minteo API handles errors in a clear and consistent way in all the scenarios that could potentially show up. The errors have been designed to give the developer quick feedback about the errors that he could be making. The structure is simple, with a few cases that cover all the scenarios in a way that they are intuitive to read and understand.

Error structure​

The errors are returned in the response body as a JSON object that looks like this:

ERROR RESPONSE
{
  "error": "UNAUTHORIZED",
  "statusCode": 401,
  "message": "Missing authorization header"
}
errorstring

The error type.

statusCodenumber

The HTTP status code of the response.

messagestring

The error message with a human-readable description of the error.

Troubleshooting​

401 Unauthorized​

This error is returned when the client is not authenticated due to:

  • The request is missing the Authorization header.
  • The Authorization header has an invalid value or is malformed. The value format must be Bearer <your API key>.
  • The API key is invalid or has been deleted.

403 Forbidden​

This error is returned when the client is authenticated but is not authorized to perform the requested action.

404 Not Found​

This error is returned when the requested resource does not exist.

422 Unprocessable​

This error is returned when the request is invalid due to:

  • The request body is missing or is malformed.
  • The request query parameters are missing or invalid.

500 Internal Server Error​

This error is returned when the server is unable to process the request due to an internal error.

info

The error codes are same for both sandbox and production environments.

Rate Limits​

The API allows up to 100,000 requests per minute. Rate limit headers are included in every response:

x-ratelimit-limit

Maximum requests allowed in the current window.

x-ratelimit-remaining

Requests remaining in the current window.

x-ratelimit-reset

Seconds until the rate limit resets.

If the rate limit is exceeded, the API will return 429 Too Many Requests:

RATE LIMIT ERROR
{
  "error": "RATE_LIMITED",
  "statusCode": 429,
  "message": "Too many requests. Please retry after a few seconds."
}

When this happens, implement exponential backoff in your retry logic.

Idempotency​

POST operations (creating payins, payouts, orders, bridges) are not idempotent. Sending the same request twice will create two separate resources.

Recommendations​

  • Check before retrying: If a request times out, query existing resources before retrying to avoid duplicates:
    • GET /v1/payins?status=PENDING to check if the payin was already created
    • GET /v1/payouts?status=PENDING for payouts
    • GET /v1/orders?status=PENDING for orders
  • Use external_identifier (available in Orders) to track operations in your system and detect duplicates
  • Implement deduplication in your application layer before calling the API

Pagination​

List endpoints (GET /v1/orders, GET /v1/payins, etc.) support page and pageSize query parameters. Responses do not include pagination metadata (total count, total pages, etc.). To check if more pages exist, request the next page and check if the response array is empty.