Error Handling

Error Response Format

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "UNKNOWN_ERROR",
  "errors": {
    "field_name": ["Error message"]
  }
}

{
  "success": false,
  "message": "Internal Server Error",
  "err_code": "SYS_INTERNAL_ERROR",
  "errors": "Unexpected error occurred. Please try again later.",
  "data": null
}

Error Categories

1. Malformed JSON/Invalid Headers

Invalid request format or header issues.

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "signature": ["Invalid Signature"]
  }
}

2. Object Integrity

Errors related to object existence or access.

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "USR_UNVERIFIED",
  "errors": {
    "customer": ["Customer not found or access denied."]
  }
}

3. Missing Required Fields

When mandatory fields are not provided.

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "REQ_FIELD_MISSING",
  "errors": {
    "customer_id": ["This field is required."],
    "tax_number": ["This field is required."]
  }
}

4. Bland Values

Empty or blank field values.

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "customer_id": ["This field may not be blank."],
    "tax_number": ["This field may not be blank."]
  }
}

5. Length Violation

Field length constraints violations.

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "name": ["Ensure this field has no more than 255 characters."]
  }
}

6. Invalid Format

Incorrect data format submissions.

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "email": ["Enter a valid email address."]
  }
}

7. Business Logic

Business rule violations and constraints.

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "transaction": ["Transaction hash already linked to a payout"],
    "email": ["Email already in use."]
  }
}

HTTP Status Codes

• 400 Bad Request: Used for all validation errors, malformed requests, and business logic violations. This includes invalid input data, missing required fields, format violations, and business rule conflicts.

• 401 Unauthorized: Returned when authentication fails or is missing. This typically occurs when API keys are invalid, expired, or not provided.

• 404 Not Found: Returned when the requested resource does not exist. This could be attempting to access an invalid endpoint or a resource that has been deleted.

• 500 Internal Server Error: Used for unexpected server-side errors. This indicates something went wrong on our servers and the request could not be completed. These errors should be reported to our support team.