API Error Handling and Error Codes Reference

When a request cannot be completed, IteraPay returns an error response with an appropriate HTTP status code. All error responses use the application/problem+json content type and follow the RFC 7807 Problem Details format.

Error response shape

Every error response includes the following fields:

string

A URI that identifies the problem type. You can use this to classify errors programmatically.

string

A short, human-readable summary of the problem type. This does not change between occurrences of the same error type.

integer

The HTTP status code for this occurrence of the problem.

string

A human-readable explanation specific to this occurrence. Use this field when surfacing errors to developers or in logs.

string

A URI reference that identifies the specific occurrence. Typically the request path.

Example error response

{
  "type": "https://example.com/probs/invalid-request",
  "title": "Invalid Request",
  "status": 400,
  "detail": "The 'amount' field must be a positive number",
  "instance": "/merchants/b0fcc813-a7ce-4bbc-932f-dbef6f59ca7f/invoices"
}

Status codes

400 Bad Request

The request body or parameters are invalid. The detail field describes the specific validation failure.

{
  "type": "https://example.com/probs/invalid-request",
  "title": "Invalid Request",
  "status": 400,
  "detail": "The 'name' field is required",
  "instance": "/merchants"
}

401 Unauthorized

The request is missing credentials, or the provided credentials are invalid. Verify your Authorization header or X-Api-Key header is set correctly.

{
  "type": "https://example.com/probs/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Bearer token is missing or has expired",
  "instance": "/merchants"
}

403 Forbidden

The credentials are valid but the authenticated identity does not have permission to perform this action. This can happen when an API key is used on a merchant it was not issued for, or when your role lacks the required permission.

{
  "type": "https://example.com/probs/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Your API key does not have access to this merchant",
  "instance": "/merchants/b0fcc813-a7ce-4bbc-932f-dbef6f59ca7f"
}

404 Not Found

The requested resource does not exist. Check that the ID or path is correct.

{
  "type": "https://example.com/probs/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Merchant 'b0fcc813-a7ce-4bbc-932f-dbef6f59ca7f' not found",
  "instance": "/merchants/b0fcc813-a7ce-4bbc-932f-dbef6f59ca7f"
}

Other status codes

All other errors use standard HTTP status codes. The type, title, and detail fields in the response body provide additional context.

Handling errors in your code

Check the HTTP status code first, then inspect type for programmatic classification and detail for a human-readable description.

const response = await fetch('https://api.iterapay.com/merchants', {
  headers: { 'Authorization': `Bearer ${token}` },
});

if (!response.ok) {
  const error = await response.json();

  switch (response.status) {
    case 400:
      console.error('Invalid request:', error.detail);
      break;
    case 401:
      console.error('Authentication failed. Check your credentials.');
      break;
    case 403:
      console.error('Permission denied:', error.detail);
      break;
    case 404:
      console.error('Resource not found:', error.instance);
      break;
    default:
      console.error(`Unexpected error ${error.status}:`, error.detail);
  }
}

Log the instance field alongside errors in your system. It identifies the exact request path where the problem occurred and makes debugging faster.

Overview

Merchants

Invoices

Transactions & Withdrawals

Settings

API Error Handling and Error Codes Reference

Error response shape

Example error response

Status codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

Other status codes

Handling errors in your code

​Error response shape

​Example error response

​Status codes

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Other status codes

​Handling errors in your code

Error response shape

Example error response

Status codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

Other status codes

Handling errors in your code