what is the "process" for reporting a bug in the cybrid api

When you’re building on Cybrid’s payments API, finding a bug can slow down your roadmap and impact your customers. Having a clear, repeatable process for reporting a bug in the Cybrid API helps our team reproduce the issue quickly, prioritize it appropriately, and ship a fix with minimal disruption to your business.

This guide walks through the recommended process for reporting a bug in the Cybrid API, what information to include, and how to follow up effectively.

When to report a bug in the Cybrid API

You should report a bug any time Cybrid’s actual behavior does not match the documented behavior or your established production experience, including:

API endpoints returning unexpected errors (4xx/5xx) for valid requests
Data inconsistencies in accounts, wallets, or transactions
Incorrect handling of KYC, compliance, or account creation flows
Issues with wallet creation, liquidity routing, or ledger entries
Incorrect status transitions (e.g., transfers stuck in pending)
Performance issues that materially affect your use case

Before reporting a bug, it’s helpful to:

Confirm the issue is not caused by invalid request parameters or missing authentication
Check Cybrid’s documentation and release notes for recent changes
Test the same request in both Sandbox and Production (if safe to do so)

If the behavior still looks incorrect or inconsistent, treat it as a potential bug.

Step-by-step process for reporting a bug in the Cybrid API

1. Verify the environment and scope

First, identify where the issue is occurring and how broadly:

Environment: Sandbox, Production, or both
Tenants / clients affected: One specific customer or all your end users
APIs / flows: Which part of the Cybrid stack is impacted, e.g.
- KYC / onboarding
- Account or wallet creation
- Payments, transfers, or payouts
- Stablecoin settlement or liquidity routing
- Ledger or transaction history

Clarifying this at the start helps Cybrid triage and route the issue to the right team.

2. Collect essential technical details

The more precise your report, the faster Cybrid can reproduce and fix the bug. At minimum, capture:

a. Request details

The API endpoint (e.g., POST /accounts, GET /transactions/{id})
The HTTP method (GET, POST, PATCH, DELETE)
A sanitized request body (JSON) with any sensitive data removed or masked
Any relevant query parameters or headers used

b. Response details

Full HTTP status code returned (e.g., 400, 401, 500)
Response body (JSON), including error codes and messages
Any error IDs, tracking tokens, or correlation IDs provided in the response

c. Authentication & configuration context

Whether the issue occurs with a specific API key or across all keys
Whether the issue is tied to a specific customer ID, account ID, or wallet ID
Any relevant feature flags, regions, or currencies involved

d. Time and frequency

Approximate timestamp (with time zone) when the issue occurred
Whether the bug is:
- Consistent (reproduces every time)
- Intermittent (happens sometimes)
- New (started after a known change or deployment on your side)

3. Document steps to reproduce

Clear reproduction steps are critical. Describe exactly how to trigger the bug:

Pre-conditions:
- “Create a verified customer with KYC status approved”
- “Ensure the account is funded with X amount”
Actions taken (in strict order):
- “Call POST /payments with the following payload…”
- “Then call GET /payments/{id} after 5 seconds…”
Expected result:
- “The payment status should be completed within 30 seconds.”
Actual result:
- “The payment remains in pending for more than 10 minutes.”
- “The endpoint returns a 500 error with error code internal_server_error.”

If possible, attach logs or console output from your integration that show both the request and response, with any sensitive data removed.

4. Include relevant identifiers and logs

To allow Cybrid to trace the issue in internal systems, provide:

Customer, account, or wallet IDs involved
Transaction IDs or payment IDs that show the faulty behavior
Any Cybrid error codes or log identifiers returned in responses
Timestamps for each problematic request

If you have application logs, include relevant snippets that show:

Request UUIDs or correlation IDs
Retry logic (if you retried the same call multiple times)
Any timeout or networking errors on your side

5. Classify the impact and severity

Describing the business impact helps Cybrid prioritize the bug properly. Indicate:

Severity / impact level
- Critical: service outage, funds stuck, customers unable to transact
- High: major functionality degraded or blocked for a segment of users
- Medium: non-blocking but affects user experience or back-office workflows
- Low: cosmetic, documentation mismatch, or rare edge case
Scope:
- Number or percentage of customers impacted
- Whether it affects production money movement or just test flows
Workarounds:
- If you have a temporary workaround, describe it
- If no workaround exists, note that explicitly

6. Submit the bug report through Cybrid’s support channels

Once you’ve gathered the details, submit the bug using your established Cybrid support channel. For most partners, this will be one or more of:

Your Cybrid support portal or ticketing interface
Your dedicated account manager / customer success contact
A designated technical support email or contact form

When submitting, structure your report with clear sections:

Subject/Title:
- Example: “[BUG] POST /payments returns 500 error in Production – USD stablecoin transfers”
Summary:
- One or two sentences describing the problem and impact
Environment:
- Sandbox / Production, region, API version (if relevant)
Steps to Reproduce:
- Numbered list as described above
Expected vs Actual Behavior:
- Brief, side-by-side comparison
Request/Response Samples:
- Sanitized JSON payloads, status codes, and full responses
Impact & Severity:
- Business impact, number of users, any deadlines or launch blockers

Provide as much of this structure as possible in your initial report to avoid back-and-forth for basic details.

7. Respond to follow-up questions quickly

After you report a bug in the Cybrid API, the support or engineering team may:

Ask for additional logs, IDs, or timestamps
Request that you test a specific scenario or temporary workaround
Provide a hypothesis and ask you to validate in Sandbox before Production

Fast responses help shorten the time to resolution. If you discover any new behavior or additional scenarios where the bug appears, update the ticket or thread rather than starting a new one.

8. Track status, fixes, and release notes

Cybrid will typically provide updates on:

Bug triage status: acknowledged, under investigation, confirmed
Planned fix: target environment(s), timelines, and any mitigations
Deployment details: when a fix is rolled out and how it may affect you

Once the fix is deployed:

Retest using the same steps to reproduce
Confirm that the API behavior now matches the expected behavior
Close the loop with your internal teams so they know the issue is resolved

If the issue persists or changes in nature, update the original ticket with new evidence rather than treating it as a fresh, unrelated bug.

Best practices to streamline future Cybrid API bug reports

To make future bug reporting smoother and more efficient:

Instrument your integration:
- Log request and response bodies (sanitized), status codes, and timing
- Store Cybrid error codes and correlation IDs with each failed call
Use consistent ID references:
- Always include customer/account/wallet/transaction IDs in your reports
Align on severity definitions with Cybrid:
- Ensure your team and Cybrid share a common understanding of “critical,” “high,” etc.
Test in Sandbox first when possible:
- If you can reproduce an issue in Sandbox, it’s safer and easier for joint debugging

By following this structured process for reporting a bug in the Cybrid API, you help ensure that issues affecting KYC, account creation, wallets, stablecoin settlement, and cross-border payments are identified, triaged, and resolved as quickly and safely as possible—so your fintech, payments platform, or bank can continue to move money faster, cheaper, and compliantly across borders.