folk uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with folk’s servers.

​
Error response

The error response contains a single error object that includes the following properties:

  • code: The code that identifies the error.
  • message: A human-readable description of the error.
  • documentationUrl: An URL to the documentation that describes the error.
  • timestamp: The timestamp when the error occurred.
  • requestId: The request identifier.
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#not-found",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

Some 4xx errors that could be handled programmatically (e.g., validation errors) include a details property that provides more information about the error. Refer to each specific error in order to see if a details property is available and its shape.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "The rate limit has been exceeded.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#rate-limiting",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "retryAfter": "2025-10-01T12:00:00Z"
    }
  }
}

​
Error list

The errors that could be returned by folk’s API are the following:

​
Bad request

Status code: 400
The request was malformed or invalid.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request was invalid.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#bad-request",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

​
Unauthorized

Status code: 401
Access to the resource is unauthorized.

This error is usually returned when the API key is invalid or not provided. Always make sure to provide an API key in the Authorization header.
Read more about authentication in the authentication section.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "No valid API key provided.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#unauthorized",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

​
Forbidden

Status code: 403
Access to the resource is forbidden.

This error is usually returned when the API key doesn’t have permissions to perform the operation.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "The API key doesn’t have permissions to perform the request.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#forbidden",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

​
Not found

Status code: 404
The requested resource was not found.

This error is usually returned when a resource that is being requested doesn’t exist.

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#not-found",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

​
Unprocessable entity

Status code: 422
The request contains invalid data.

This error is usually returned when there is a validation error in the body or query parameters of the request.

The details object includes an array of issues describing each validation rule that has failed validation. You can find an exaustive list of all available properties on the official Zod documentation.

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Invalid query parameters",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#unprocessable-entity",
    "details": {
      "issues": [
        {
          "code": "too_small",
          "minimum": 1,
          "type": "number",
          "inclusive": true,
          "exact": false,
          "message": "Number must be greater than or equal to 1",
          "path": ["limit"]
        }
      ]
    },
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

​
Rate limiting

Status code: 429
The rate limit for the operation has been exceeded.

The details object offers additional information about the rate limit and the reset time. It includes the following properties:

  • limit: The maximum number of requests allowed per minute.
  • remaining: The number of requests remaining in the current rate limit window.
  • retryAfter: The ISO 8601 Datetime when the rate limit will be reset.

Read more about rate limits in the rate limits section.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "The rate limit has been exceeded.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#rate-limiting",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "retryAfter": "2025-10-01T12:00:00Z"
    }
  }
}

​
Internal server error

Status code: 500
An error occurred on the server.

If this error is returned, it means folk’s servers encountered an error while processing the request.
If the error persists, please contact support and include the requestId shown in the response.

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An internal server error occurred.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#internal-server-error",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

​
Service unavailable

Status code: 503
The service is temporarily unavailable.

If this error is returned, it means folk’s servers are temporarily unavailable.
folk strives to keep the service available at all times, but sometimes it’s necessary to perform maintenance or upgrades.

If the error persists, please contact support and include the requestId shown in the response.

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The service is currently unavailable.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#service-unavailable",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}