> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fraudeg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FraudEG API Error Codes and HTTP Status References

> Reference for FraudEG API HTTP status codes and error objects. Covers authentication errors, validation failures, rate limits, and server errors.

When a request cannot be completed, FraudEG returns a JSON error object in the response body alongside the appropriate HTTP status code. Every error response follows the same structure, so you can handle failures consistently across all endpoints without writing endpoint-specific error parsing logic.

## Error Response Structure

All error responses contain a single top-level `error` object with the following fields:

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "doc_url": "https://docs.fraudeg.com/authentication",
    "request_id": "req_8f3k2p9q"
  }
}
```

<ResponseField name="error.code" type="string" required>
  A stable, machine-readable string identifying the error type. Use this field in your error-handling logic — do not parse the `message` string, as its wording may change.
</ResponseField>

<ResponseField name="error.message" type="string" required>
  A human-readable explanation of what went wrong. Useful for logging and debugging, but not intended for display to end users.
</ResponseField>

<ResponseField name="error.doc_url" type="string">
  A direct link to the relevant documentation page for this error type. Not present on all error responses.
</ResponseField>

<ResponseField name="error.request_id" type="string" required>
  A unique identifier for the specific request that failed. Always include this value when contacting FraudEG support — it allows the support team to locate the exact request in internal logs.
</ResponseField>

<Note>
  Save the `request_id` from any error response before filing a support ticket at [support.fraudeg.com](https://support.fraudeg.com). Without it, diagnosing intermittent or environment-specific issues takes significantly longer.
</Note>

## HTTP Status Codes

FraudEG uses standard HTTP status codes. The table below describes every code you may encounter.

| Status Code | Name                  | Meaning                                                                                                                                 |
| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `200`       | OK                    | Request succeeded. The response body contains the requested resource or action result.                                                  |
| `201`       | Created               | Resource created successfully. The response body contains the new resource.                                                             |
| `202`       | Accepted              | The request was accepted for asynchronous processing. Poll the relevant resource or listen for a webhook event to get the final result. |
| `204`       | No Content            | The request succeeded and there is no response body to return. Returned by some `DELETE` operations.                                    |
| `400`       | Bad Request           | Invalid request body or missing required fields. Fix the request before retrying.                                                       |
| `401`       | Unauthorized          | Missing or invalid API key. Check your `Authorization` header.                                                                          |
| `403`       | Forbidden             | Your API key does not have permission to access this resource or endpoint.                                                              |
| `404`       | Not Found             | The resource identified by the given ID does not exist, or the endpoint path is incorrect.                                              |
| `409`       | Conflict              | The `Idempotency-Key` you provided was already used with different request parameters.                                                  |
| `422`       | Unprocessable Entity  | The request was syntactically valid but could not be processed due to a logical conflict.                                               |
| `429`       | Too Many Requests     | You have exceeded the rate limit for this endpoint. Back off and retry.                                                                 |
| `500`       | Internal Server Error | An unexpected error occurred on FraudEG servers. Retry with exponential backoff.                                                        |
| `503`       | Service Unavailable   | FraudEG is experiencing a temporary outage. Check [status.fraudeg.com](https://status.fraudeg.com) for updates.                         |

## Error Code Reference

The following error codes appear in the `error.code` field of error responses. Expand each entry for a description and resolution steps.

<Accordion title="invalid_api_key">
  **What it means:** Your API key is missing from the request, is malformed, or has been revoked.

  **How to resolve:**

  * Confirm you are passing the key in the `Authorization: Bearer <API_KEY>` header.
  * Verify the key is copied in full with no leading or trailing whitespace.
  * Check the FraudEG dashboard under **Settings → API Keys** to confirm the key is active and has not been revoked.
  * Generate a new key if the original has been revoked or lost.
</Accordion>

<Accordion title="insufficient_permissions">
  **What it means:** Your API key does not have the required scope to call this endpoint.

  **How to resolve:**

  * Review the scopes assigned to your key in **Settings → API Keys**.
  * Create a new key with the appropriate scopes, or ask your account administrator to update the existing key's permissions.
  * Refer to the individual endpoint documentation to see which scope it requires.
</Accordion>

<Accordion title="missing_required_field">
  **What it means:** A required field is absent from the request body. The error object will include a `param` field identifying which field is missing.

  **How to resolve:**

  * Read the `param` value to identify the missing field.
  * Consult the endpoint's request body documentation to confirm all required fields are present and correctly named (field names are case-sensitive).
  * Ensure your `Content-Type: application/json` header is set, as omitting it prevents FraudEG from parsing the request body.
</Accordion>

<Accordion title="invalid_field_value">
  **What it means:** A field in the request body has a value that is out of the allowed range, is the wrong data type, or does not match an expected enum value.

  **How to resolve:**

  * Check the `param` field in the error response to identify which field is invalid.
  * Review the allowed values, types, and ranges documented for that field on the relevant endpoint page.
  * Common examples: passing a string where an integer is expected, sending a negative `amount`, or using an unsupported `currency` code.
</Accordion>

<Accordion title="resource_not_found">
  **What it means:** No resource exists for the ID provided in the request path or body.

  **How to resolve:**

  * Confirm the resource ID is correct and belongs to your account.
  * Check that you are targeting the correct environment — IDs from the sandbox do not exist in production, and vice versa.
  * Verify the resource has not been deleted.
</Accordion>

<Accordion title="rate_limit_exceeded">
  **What it means:** Your integration has sent too many requests to this endpoint within the current rate limit window.

  **How to resolve:**

  * Read the `Retry-After` response header to determine how many seconds to wait before retrying.
  * Implement exponential backoff in your retry logic.
  * See the [Rate Limits](/api-reference/rate-limits) page for per-endpoint limits and best practices for staying within them.
</Accordion>

<Accordion title="idempotency_conflict">
  **What it means:** You submitted a request with an `Idempotency-Key` that was previously used, but the request body in the current request does not match the original request body.

  **How to resolve:**

  * Do not reuse idempotency keys across logically different operations. Each unique operation should have its own key, typically a UUID v4.
  * If you are retrying a failed request, make sure the request body is byte-for-byte identical to the original.
  * Idempotency keys expire after 24 hours; after that, the same key can be reused safely.
</Accordion>

<Accordion title="service_unavailable">
  **What it means:** FraudEG is experiencing a temporary issue that prevents it from processing requests. This is not caused by your request.

  **How to resolve:**

  * Retry the request with exponential backoff starting at a 1-second delay.
  * Monitor [status.fraudeg.com](https://status.fraudeg.com) for incident updates and estimated resolution times.
  * If the condition persists beyond a few minutes, contact [support.fraudeg.com](https://support.fraudeg.com) with the `request_id` from the error response.
</Accordion>

## Retry Guidance

Not all errors are safe to retry. Follow this guidance to avoid duplicate operations and unnecessary load:

| Scenario                    | Safe to Retry? | Guidance                                                                        |
| --------------------------- | -------------- | ------------------------------------------------------------------------------- |
| `500 Internal Server Error` | ✅ Yes          | Retry with exponential backoff.                                                 |
| `503 Service Unavailable`   | ✅ Yes          | Retry with exponential backoff; monitor status page.                            |
| `429 Too Many Requests`     | ✅ Yes          | Wait for `Retry-After` seconds, then retry.                                     |
| `400 Bad Request`           | ❌ No           | Fix the request body before retrying.                                           |
| `401 Unauthorized`          | ❌ No           | Resolve the authentication issue before retrying.                               |
| `403 Forbidden`             | ❌ No           | Update API key permissions before retrying.                                     |
| `404 Not Found`             | ❌ No           | Confirm the resource ID exists and belongs to your account before retrying.     |
| `409 Conflict`              | ❌ No           | Use a new `Idempotency-Key` or match the original request body before retrying. |
| `422 Unprocessable Entity`  | ❌ No           | Investigate the logical conflict before retrying.                               |

<Tip>
  Use the `Idempotency-Key` header on all `POST` requests so that retries on `500` or `503` errors never result in duplicate resources or double-charged transactions.
</Tip>