Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.iterapay.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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:
​
type
string
A URI that identifies the problem type. You can use this to classify errors programmatically.
​
title
string
A short, human-readable summary of the problem type. This does not change between occurrences of the same error type.
​
status
integer
The HTTP status code for this occurrence of the problem.
​
detail
string
A human-readable explanation specific to this occurrence. Use this field when surfacing errors to developers or in logs.
​
instance
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.