Troubleshooting

This guide covers authentication failures, invalid requests, transaction errors, pagination problems, and general connectivity issues.

The examples primarily focus on InfraRails. For Hyperhash and Foundry, consult the relevant product documentation as their API interfaces become available.

Before you begin

When an API request fails, start by checking the following:

1. Confirm that you are using the correct API environment.
2. Verify the endpoint path and HTTP method.
3. Check that your API credentials are valid.
4. Confirm that all required parameters are present.
5. Validate your JSON request body.
6. Inspect the HTTP response status and error message.
7. Preserve the request identifier for troubleshooting.

For financial operations, avoid automatically repeating a request until its outcome is understood.

HTTP status codes

The following table provides general guidance for common HTTP responses.

These are standard HTTP interpretations. The actual response codes and error formats depend on the endpoint and deployment configuration.

Authentication issues

My API request returns 401 Unauthorized

A 401 response generally indicates that authentication information is missing, invalid, or not accepted.

Possible causes:

• Missing API credentials.
• Invalid or expired credentials.
• Incorrect authentication header.
• Using a key from another environment.
• Using the wrong credential type.

Recommended steps:

1. Confirm that the API key is valid.
2. Verify that it belongs to the intended environment.
3. Check the required authentication header.
4. Confirm that the credential has not been revoked.
5. Retry only after correcting the authentication issue.

For InfraRails, ledger API requests use the x-api-key header.

My API request returns 403 Forbidden

A 403 response generally indicates that the request is not permitted.

Possible causes:

• The credential does not have access to the requested resource.
• The API key belongs to another ledger.
• The ledger is not in a permitted state.
• An API Gateway management key is not associated with the required usage plan.
• The request fails an ownership or authorization check.

Recommended steps:

1. Verify the ledger identifier.
2. Confirm that the credential belongs to the intended ledger.
3. Check the ledger's current status.
4. Verify the API Gateway usage-plan configuration for management endpoints.
5. Review the applicable authorization requirements.

My API key stopped working after rotation

InfraRails ledger API key rotation is designed to invalidate the previous key immediately.

Recommended steps:

1. Confirm that the application uses the replacement credential.
2. Update the secret in the appropriate configuration system.
3. Restart or refresh services that cache credentials.
4. Verify the correct ledger and environment.
5. Test an authorized read operation.

Never expose the replacement key in application logs or support requests.

API Gateway and connectivity

I receive a Missing Authentication Token error

For an AWS API Gateway REST API, this message can indicate that the requested resource or method is unavailable at the specified URL.

It may also occur when a request fails certain authentication checks.

Check:

• The API Gateway base URL.
• The deployment stage.
• The endpoint path.
• The HTTP method.
• Whether the API has been deployed after route changes.

For example, confirm that a request intended for the prod stage includes the correct stage prefix when using the default API Gateway URL.

I receive a 502 Bad Gateway error

A 502 response may indicate a problem between API Gateway and the Lambda integration.

Possible causes include:

• An invalid Lambda proxy response.
• An unhandled function error.
• Incorrect integration configuration.
• Missing Lambda invocation permission.

Recommended steps:

1. Check the API Gateway execution logs where enabled.
2. Review the relevant Lambda CloudWatch logs.
3. Verify Lambda proxy integration.
4. Confirm API Gateway has permission to invoke the function.
5. Validate the Lambda response structure.

My endpoint returns 404 after being added

The API Gateway deployment may not include the new route.

Recommended steps:

1. Confirm the resource and method exist.
2. Verify the Lambda integration.
3. Deploy the API to the correct stage.
4. Check the request URL.
5. Confirm the Lambda router recognizes the path.

For example, the InfraRails transaction lookup endpoint requires a route for:

GET /transactions/lookup

My browser reports a CORS error

Cross-Origin Resource Sharing (CORS) errors can occur when a browser application sends requests across different origins.

Check:

• The allowed origins.
• Supported HTTP methods.
• Allowed request headers.
• OPTIONS preflight handling.
• CORS headers on successful and error responses.

For InfraRails, ensure the configuration accounts for the x-api-key and Content-Type headers.

Privileged financial API credentials should remain on a trusted backend rather than being exposed in frontend code.

Request validation

My request returns 400 Bad Request

A 400 response commonly indicates that the request does not satisfy the endpoint's validation requirements.

Check:

• Required fields.
• JSON syntax.
• Supported enum values.
• Identifier formats.
• Amount types.
• Currency compatibility.
• Query parameter values.

Refer to the endpoint's API Reference for the exact request schema.

My transaction amount is incorrect

InfraRails uses integer minor units.

For EUR with exponent 2:

For example, submitting 100 represents €1.00 rather than €100.00 for an EUR account with exponent 2.

Always check the account's currency exponent.

My transaction is rejected because of insufficient funds

The source account may not have sufficient available balance for the requested operation.

Recommended steps:

1. Retrieve the account balance.
2. Confirm the intended amount and currency.
3. Check any applicable charges.
4. Review pending financial activity.
5. Confirm the account is permitted to transact.

Do not manually alter the stored account balance to bypass validation.

Transaction processing

My transaction remains PENDING

A PENDING transaction has not reached a completed state.

Depending on the workflow, it may require further processing or an authorized status transition.

Recommended steps:

1. Retrieve the transaction.
2. Check its current status.
3. Determine whether an external workflow is involved.
4. Review relevant application or provider logs.
5. Follow the documented transaction lifecycle.

Do not assume that a pending transaction has completed its financial effects.

What does INFLIGHT mean?

INFLIGHT indicates that a transaction is in an intermediate processing state.

Applications should continue tracking the operation until an appropriate terminal outcome is reached.

My transaction returns 409 Conflict

A conflict may indicate:

• Reuse of an idempotency key with different request parameters.
• An unsupported transaction status transition.
• A concurrent operation affecting the same resource.
• A conflicting account or transaction state.

Recommended steps:

1. Preserve the original request information.
2. Retrieve the existing transaction where possible.
3. Inspect its current status.
4. Compare the request parameters.
5. Resolve the conflict before attempting another operation.

Do not generate a new idempotency key merely to bypass an unresolved conflict.

My transaction request timed out

A timeout does not prove that the transaction failed.

The server may have processed the operation without successfully returning a response.

Recommended steps:

1. Preserve the original idempotency key.
2. Use the supported transaction lookup operation.
3. Check whether a transaction already exists.
4. Inspect the transaction's current status.
5. Retry only when safe under the documented API behavior.

Can I retry a completed transaction?

A completed transaction should not be treated as an unsuccessful request.

If a new financial movement is required, create a separate authorized business operation.

If the original transaction requires correction, use the appropriate supported accounting workflow.

Account issues

I cannot create a transaction using an account

Possible causes include:

• The account is suspended or closed.
• The account belongs to another ledger.
• The currency is incompatible with the operation.
• The available balance is insufficient.
• The account identifier is invalid.

Verify the account details and the transaction requirements.

I cannot close an account

The InfraRails account lifecycle implementation requires balance conditions to be satisfied before closure.

Check that:

• The available balance is zero.
• The pending balance is zero.
• The account is in an eligible lifecycle state.
• There are no unresolved operations or external obligations that must be addressed.

The deployed implementation's closure checks should be verified before relying on account closure in production.

Can a closed account be reopened?

The current InfraRails account lifecycle design treats CLOSED as a terminal state.

The account status endpoint does not support reactivating closed accounts.

Pagination and filtering

My pagination token is rejected

A nextToken may be invalid because:

• It was modified.
• It belongs to another resource or ledger.
• The request filters changed.
• It was generated using a different signing secret.
• It is incompatible with the current API implementation.

Recommended steps:

1. Preserve the token exactly as returned.
2. Use the same resource and filters.
3. Verify the correct environment.
4. Start a new pagination sequence if necessary.

My paginated response contains fewer records than the requested limit

This can occur when filtering is applied after DynamoDB retrieves a page of records.

A response may contain fewer matching items than the requested limit.

Continue using nextToken until it is null.

My response contains an empty data array but a nextToken

An empty page does not necessarily mean that no additional matching records exist.

Continue pagination while a valid continuation token is present.

I cannot find a recently created transaction

A lookup using a secondary index may be subject to eventual consistency.

A recently created transaction might not immediately appear in a lookup result.

For critical financial operations, use the supported authoritative transaction retrieval and recovery process before creating another operation.

Logs and diagnostics

What information should I collect when an issue occurs?

Collect the following information when available:

Do not include API keys, passwords, or sensitive customer information.

How can I investigate Lambda errors?

If you operate the infrastructure, use Amazon CloudWatch to inspect the relevant Lambda logs.

Correlate requests using request identifiers and timestamps.

Review:

• Initialization errors.
• Application exceptions.
• DynamoDB errors.
• Authentication failures.
• Integration timeouts.
• Transaction conflicts.

Ensure that logs do not expose sensitive financial data or credentials.

When to contact support

Contact support when:

• An error persists after validating the request.
• A financial transaction has an uncertain outcome.
• Authentication fails despite verified credentials.
• An API endpoint behaves differently from its documentation.
• You identify a possible accounting inconsistency.
• You suspect a security issue.

Include the relevant diagnostic information without sharing secrets.

For assistance, see Support → Contact Support.

Related documentation

• Getting Started — Initial API integration guidance.
• Authentication — API credentials and access requirements.
• Errors & Status Codes — API error handling.
• Idempotency — Safe financial operation retries.
• InfraRails → Transaction Lifecycle — Transaction processing states.
• API Reference — Endpoint-specific request and response contracts.
• Changelog → API Changes — Published API modifications.

---

This guide describes common troubleshooting scenarios and the current InfraRails development architecture. Actual error responses, supported recovery operations, and endpoint availability depend on the deployed API version.