FraudEG API Error Codes and HTTP Status References

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:

{
  "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"
  }
}

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.

string

required

A human-readable explanation of what went wrong. Useful for logging and debugging, but not intended for display to end users.

string

A direct link to the relevant documentation page for this error type. Not present on all error responses.

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.

Save the request_id from any error response before filing a support ticket at support.fraudeg.com. Without it, diagnosing intermittent or environment-specific issues takes significantly longer.

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 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.

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.

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.

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.

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.

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.

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 page for per-endpoint limits and best practices for staying within them.

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.

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 for incident updates and estimated resolution times.
If the condition persists beyond a few minutes, contact support.fraudeg.com with the request_id from the error response.

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.

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.

Overview

Transactions

Identity

Monitoring

FraudEG API Error Codes and HTTP Status References

Error Response Structure

HTTP Status Codes

Error Code Reference

Retry Guidance

​Error Response Structure

​HTTP Status Codes

​Error Code Reference

​Retry Guidance

Error Response Structure

HTTP Status Codes

Error Code Reference

Retry Guidance