Error Handling

Most Fangate API endpoints use the application's standard JSON envelope:

{
  "success": true,
  "errors_message": null,
  "data": {}
}

For failures:

{
  "success": false,
  "errors_message": "Human readable message",
  "data": null
}

Important exception

Not every endpoint uses the standard wrapper.

Current notable exceptions include:

• GET /api/veriff/create
• POST /api/veriff/decision
• GET /api/maps/autocomplete
• POST /api/report
• POST /api/yoti/session/create
• POST /api/yoti/webhook

These endpoints should be handled according to their endpoint-specific schemas in the API reference.

Common status codes

Status	Meaning	Typical cause
200	Success	Standard successful request
201	Created	Resource created successfully
202	Accepted	Async processing has started, but work is not finished yet
204	No content	Request succeeded without a response body
400	Bad request	Invalid body or malformed request
401	Unauthorized	Missing or invalid bearer token
403	Forbidden	Token is valid, but user cannot access the resource
404	Not found	Resource id or route target does not exist
422	Validation / business rule failure	Rule violation, workflow constraint, or additional action required
500	Internal server error	Unexpected backend failure

Validation failures

Validation failures may appear as:

• the standard success=false envelope with errors_message
• Laravel-style validation payloads for endpoints that do not use the wrapper

Examples:

{
  "success": false,
  "errors_message": "The email has already been taken.",
  "data": null
}

or, for a non-wrapped validation response:

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email has already been taken."
    ]
  }
}

Async upload / processing responses

Some content-creation and upload flows can return 202 Accepted.

This means:

• Fangate has accepted the request
• background processing is still happening
• the client must poll the documented status endpoint or refresh the resource later

This is especially important for:

• upload sessions
• large legacy direct uploads
• consent flows where media is not fully ready yet

Consent-tag verification response

When a tagged creator tries to accept or decline a consent tag before completing Veriff, Fangate currently returns a verification-required response instead of applying the decision immediately.

Expect fields such as:

{
  "success": false,
  "errors_message": "Verification required",
  "data": {
    "requires_verification": true,
    "verification": {
      "url": "https://..."
    }
  }
}

Upload and storage failures

Common failure categories in upload flows:

• staged upload expired
• multipart part list invalid
• completion called before all required parts exist
• storage provider returned an error
• finalization job failed after upload

Client guidance:

1. treat presigned-upload instructions as time-limited
2. retry upload-session polling before recreating the entire product
3. if finalization fails, surface the backend message and restart the upload flow cleanly

Authentication and authorization failures

Scenario	Expected result
Missing bearer token	401
Invalid / revoked bearer token	401
Accessing another creator's product or wallet data	403
Acting on a consent tag that does not belong to the caller	403 or 404 depending on resolution path

Error-handling recommendations

• Always check the HTTP status code first.
• Then inspect success, errors_message, and data where the standard envelope is used.
• Do not assume that 200 means the workflow is fully complete. Some flows use follow-up status checks.
• Do not assume every validation failure has the same JSON shape.
• Log raw backend responses during integration until your client is stable.