Errors

All API errors follow a consistent format and include helpful details.

Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "amount",
        "message": "Amount must be positive"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Unprocessable Entity
429	Too Many Requests
500	Internal Server Error

Error Codes

Authentication Errors

Code	Description	Resolution
UNAUTHORIZED	Missing or invalid credentials	Check API key
FORBIDDEN	Insufficient permissions	Request proper scopes
TOKEN_EXPIRED	Access token expired	Refresh the token

Validation Errors

Code	Description	Resolution
VALIDATION_ERROR	Invalid request data	Check field requirements
INVALID_FORMAT	Malformed request	Verify JSON format
MISSING_FIELD	Required field missing	Include all required fields

Resource Errors

Code	Description	Resolution
NOT_FOUND	Resource doesn't exist	Check the ID
ALREADY_EXISTS	Duplicate resource	Use different identifier
CONFLICT	State conflict	Retry with fresh data

Rate Limit Errors

Code	Description	Resolution
RATE_LIMITED	Too many requests	Wait and retry

Compliance Errors

Code	Description	Resolution
SHARIAH_VIOLATION	Contract violates Shariah	Review contract terms
JURISDICTION_ERROR	Not allowed in jurisdiction	Check local regulations
COMPLIANCE_FAILED	Compliance check failed	Review requirements

Handling Errors

TypeScript/JavaScript

try {
  const contract = await iof.contracts.create({ ... });
} catch (error) {
  if (error instanceof IOFError) {
    console.error(error.code, error.message);

    if (error.code === "VALIDATION_ERROR") {
      error.details.forEach(d => {
        console.error(`${d.field}: ${d.message}`);
      });
    }
  }
}

Python

try:
    contract = iof.contracts.create(...)
except IOFError as error:
    print(f"{error.code}: {error.message}")

    if error.code == "VALIDATION_ERROR":
        for detail in error.details:
            print(f"{detail['field']}: {detail['message']}")

Request IDs

Every response includes a request ID:

{
  "meta": {
    "requestId": "req_abc123def456"
  }
}

Include this ID when contacting support.

Next Steps

• Rate Limits - Rate limiting info
• Authentication - Auth errors