Errors

Most error handling is managed by Fiskil. However, in some cases your Resource Server must return errors to indicate why data cannot be shared.

Consistent use of error codes allows Data Recipients to understand outcomes and enables Fiskil to meet compliance and reporting requirements.

Status Codes

403 — Forbidden

Returned when Fiskil is not allowed to access the requested data.

Examples:

• Authentication failed between Fiskil and your Resource Server.
• The data request could cause physical or financial harm to an entity.

To distinguish a refusal from an ordinary 403, set the response header:

X-Sharing-Refused: true

This distinction is required for CDR Data Holder reporting.

404 — Not Found

Returned when the resource ID in the request path does not exist for the customer.

Example:

GET /v1/energy/customer/customer-id/accounts/not-a-real-account

If not-a-real-account is not linked to the given customer, return 404.

Also return 404 when the requested resource is associated with a blocked or suspended account. In this case, set the X-Sharing-Refused header as described above.

422 — Unprocessable Entity

Returned when the resource ID in the request body does not exist for the customer.

Example:

POST /v1/energy/customer/customer-id/accounts
{
  "data": {
    "accountIds": [
      "not-a-real-account"
    ]
  }
}

If the account ID is invalid, return 422.

Also return 422 when the account is blocked or suspended, with X-Sharing-Refused header set.

500 — Internal Server Error

Returned for unexpected exceptions in your Resource Server.

Examples:

• Database connection loss
• Unhandled runtime error

Summary

• Use 403, 404, 422, 500 consistently.
• Include the X-Sharing-Refused header where refusal is required to capture these events for CDR reporting.
• Return errors in the standard JSON format.