Error Reference

This page documents every error response the valueverde Partner API can return, organized by HTTP status code.

Standard Error Response Format

All error responses follow a consistent JSON structure:

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE"
}

Field	Type	Description
`error`	string	A human-readable description of what went wrong
`code`	string	A machine-readable error code for programmatic handling

Always check for the error field to detect failures. Use code for branching logic in your application.

The request is malformed or contains invalid data.

Code	Error Message	Endpoint(s)	Resolution
`VALIDATION_ERROR`	"Missing required fields"	`/api-applications`	Include all required fields in the request body
`CONSENT_REQUIRED`	"All consent fields must be explicitly accepted (true)"	`/api-applications`	Set `terms_and_statute_consent` and `data_sharing_consent` to `true`
`INVALID_IBAN`	"Invalid IBAN format"	`/api-applications`	Provide a valid IBAN
`INVALID_COOPERATIVE`	"Cooperative not found"	`/api-applications`	Provide a valid `cooperative_id`
`INVALID_SHARES`	"Minimum 1 shares required" / "Maximum N shares allowed"	`/api-applications`	Request between 1 and the cooperative's maximum allowed shares

Authentication credentials are missing or invalid.

Code	Error Message	Endpoint(s)	Resolution
`MISSING_API_KEY`	"API key required"	All endpoints	Include the `X-API-Key` header in your request
`INVALID_API_KEY`	"Invalid API key"	All endpoints	Verify your API key is correct

The API key is recognized but not authorized for this operation.

Code	Error Message	Endpoint(s)	Resolution
`CLIENT_INACTIVE`	"API client inactive"	All endpoints	Contact partners@valueverde.de to reactivate your account
`UNAUTHORIZED`	"Partner not authorized to manage applications"	`/api-applications`	Your partner account requires the `can_manage_applications` permission

The requested resource does not exist.

Code	Error Message	Endpoint(s)	Resolution
`NOT_FOUND`	"Cooperative not found"	`/api-projects`	Verify the cooperative ID or name is correct
`NOT_FOUND`	"Application not found"	`/api-applications`	Verify the application ID belongs to your partner account

The HTTP method is not supported for this endpoint.

An unexpected error occurred on the server.

Code	Error Message	Resolution
`SERVER_ERROR`	"Internal server error"	Retry after a short delay. If the error persists, contact partners@valueverde.de with the request details.

Always check the error field -- Do not rely solely on HTTP status codes. The code field provides the specific failure reason for programmatic handling.
Implement retry logic for 5xx errors -- Server errors are typically transient. Use exponential backoff (e.g., 1s, 2s, 4s) with a maximum of 3 retries.
Do not retry 4xx errors -- Client errors (400, 401, 403, 404) indicate a problem with your request. Fix the request before retrying.
Log error responses -- Store the full error response (including code and error message) for debugging. This information is essential when contacting support.